The module processes document frames of InDesign® documents.

Here you will find examples to use frame.

Version :
17.12.2024, 12:52 Uhr

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

static int is_valid(ItemRef itemRef)

Does the reference point to an existing frame?

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

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

Version 1.4.1 R383, 28. June 2007

priint:comet InDesign® Plug-Ins, Illustrator

item::defined
comet.CPageItem.isValid

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

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

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

From comet_pdf only rectangular frames are supported!

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

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

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

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

0 : horizontal
1 : vertical

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

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

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

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

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

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

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

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

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

#include "internal/types.h"

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

#include "internal/types.h"

int main ()
{
    ItemRef	frame	= item::alloc ();
    int		result;

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

    item::release (frame);
    return 0;
}

Create a simple spline in original size. 

#include "internal/types.h"

int main ()
{
    ItemRef 		fr	= item::alloc ();

    frame::create (
     	fr,						// the new created frame
     	kSpline,				// type
     	0.0, 0.0, 0.0, 0.0,		// bbox
     	1, "",					// page num and layer
     	1,						// columns
     	0,						// text orientation
     	-1.0,					// gutter
     	kCS, 103.37085648896758, -226.77165354330714, 	50.929911606987304, -222.51968503937013, 	155.81180137094785, -231.02362204724415,
     	kCS, 116.12676200077863, -58.11023622047246, 	175.65432105589673, -102.0472440944882, 	56.59920294566052, -14.17322834645671,
     	kCS, 29.67006908739279, -113.38582677165356, 	-8.597647448040284, -55.27559055118111, 	67.93778562282587, -171.49606299212599);

    return 0;
}

kCS, kCK and kL since v4.2 R33520.

priint:comet InDesign® Plug-Ins, comet_pdf

create_textframe
document::pages
document::page
layer

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

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

#include "internal/types.h"

Version 1.3.4 (P/R 74)

priint:comet InDesign® Plug-Ins, comet_pdf

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

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

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

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

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

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

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

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

0 : No
1 : Yes. If you duplicate into an other document, the parameter has no effect! 
int main ()
{
    int		res;
    ItemRef	resref	= item::alloc ();

    res = frame::duplicate (resref, gFrame, 10.0, 10.0);
    wlog ("", "duplicate result : %d (%d --> %d)\n",
     	res, item::getint (gFrame), item::getint (resref));

    item::release(resref);

    return 0;
}

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

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

comet.CFrame.duplicate

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

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

If the script frame is a member of a Comet group and is on the same spread as the newly created frame, the new frame will become a member of this Comet group aswell.

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

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

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

0 : horizontal
1 : vertical

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

int		pg  	= 1;
ItemRef	frame  	= item::alloc ();
char	layerName[256];
int		result;

result = frame::create_textframe (
 			frame,
 			10, 10, 200, 200,
 			pg,
 			layer::name (2, layerName));


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

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

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

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

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

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

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

0 : horizontal
1 : vertical

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

ItemRef		frame  	= item::alloc ();
char		layerName[256];
int			result;

result = frame::create_textframe_f (
 			frame,
 			10.0, 10.0, 200.5, 200.5,
 			document::page (),
 			layer::name (2, layerName));

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

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

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

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

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

0 : horizontal
1 : vertical 
int main ()
{
    ItemRef		frame	= item::alloc ();
    ItemRef		subframe= item::alloc ();
    char		layerName[256];
    int			result;

    result = frame::create_textframe (
     		frame,
     		10, 210, 300, 400,
     		2,
     		layer::name (2, layerName));
    if (result != 0)
    {
        showmessage ("Error %d",result);
        item::release (frame);
        return 1;
    }

    result 	= frame::create_subtextframe (
     		subframe,
     		0, 0, 100, 40,
     		frame,
     		3, 8.3);

    frame::select (frame);
    item::release (frame);
    item::release (subframe);

    return 1;
}

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

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

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

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

create_subtextframe

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

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

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

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

0 : stroke bounds
1 : path bounds

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

int main ()
{
    float		l, t, r, b;
    float		w, h;

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

    return 0;
}

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

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

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

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

see frame::get_size

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

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

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

0 : stroke bounds
1 : path bounds

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

int main ()
{
    float		l, t, r, b;
    float		w, h;

    frame::bbox (gFrame, &l, &t, &r, &b);
    frame::get_size (gFrame, &w, &h);
    wlog ("", "Frame %d : %f x %f (%f x %f)\n",
    item::getint (gFrame),
    r-l, b-t,
    w, h);

    frame::resize (gFrame,w, h+20.0, 0, 0);
    return 0;
}

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

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

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

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

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

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

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

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

0 : page relative
1 : spread relative

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

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

int main ()
{
    float x, y;
    float x8, y8;
    float l, t, r, b;

    frame::bbox (gFrame, &l, &t, &r, &b);
    frame::refpoint (gFrame, 0, &x, &y);
    frame::refpoint (gFrame, 8, &x8, &y8);
    frame::moveto (gFrame, x8+(x-l), y8+(y-t));

    return 0;
}

v4.0.5 R18123, 12. Mai 2017

priint:comet InDesign® Plug-Ins, comet_pdf

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

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

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

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

Version 3.1, R1550, 18. Sept. 2009

priint:comet InDesign® Plug-Ins, comet_pdf

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

int main ()
{
    float x, y;
    float x8, y8;
    float l, t, r, b;

    frame::bbox (gFrame, &l, &t, &r, &b);
    frame::refpoint (gFrame, 0, &x, &y);
    frame::refpoint (gFrame, 8, &x8, &y8);
    frame::moveto (gFrame, x8+(x-l), y8+(y-t));

    return 0;
}

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

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

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

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

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

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

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

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

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

Name Type Default Description
Return int   0 or ErrorCode

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

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

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

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

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

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

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

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

int main ()
{
    float		l, t, r, b;
    float		w, h;

    frame::bbox (gFrame, &l, &t, &r, &b);
    frame::get_size (gFrame, &w, &h);
    wlog ("", "Frame %d : %f x %f (%f x %f)\n",
    item::getint (gFrame),
    r-l, b-t,
    w, h);

    frame::resize (gFrame,w, h+20.0, 0, 0);

    return 0;
}

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

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

comet.CPageItem.setSize

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

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

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

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

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

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

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

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

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

int main ()
{
    String layerName = string::alloc("ASDF");

    frame::move_to_layer (gFrame, layerName);
    string::release(layerName);

    return 0;
}

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

int get_top (ItemRef fr, ItemRef top)
{
    ItemRef		parent	= item::alloc ();
    ItemRef		child	= item::alloc ();

    item::assign (top, fr);
    item::assign (child, fr);

    while (frame::get_group (child, parent) == 0)
    {
        item::assign (child, parent);
        item::assign (top, parent);
    }

    item::release (parent);
    item::release (child);

    return frame::is_valid (top);
}

int main ()
{
    ItemRef		top		= item::alloc ();

    if (!get_top (gFrame, top))	return 0;

    frame::move_to_layer (top, "Ebene 2");

    return 0;
}

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

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

move_to_ilayer
layer
get_group
comet.CPageItem.setLayer

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

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

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

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

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

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

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

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

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

int get_top (ItemRef fr, ItemRef top)
{
    ItemRef		parent	= item::alloc ();
    ItemRef		child	= item::alloc ();

    item::assign (top, fr);
    item::assign (child, fr);

    while (frame::get_group (child, parent) == 0)
    {
        item::assign (child, parent);
        item::assign (top, parent);
    }

    item::release (parent);
    item::release (child);

    return frame::is_valid (top);
}

int main ()
{
    ItemRef		top		= item::alloc ();

    if (!get_top (gFrame, top))	return 0;

    frame::move_to_layer (top, "Ebene 2");

    return 0;
}

1.0.20
Parameter mvGroup since version 3.2 R2245, 18.01.2011

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

move_to_ilayer
layer
comet.CPageItem.setLayer

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

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

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


priint:comet InDesign® Plug-Ins, comet_pdf

create_subtextframe_f
count_columns
document::find_frame
document::insert_macro

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

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

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

0 : current script frame (since R2222)
gutter float* 0 Gutter width in points 
int main ()
{
    int			cols;
    float		gut;
    int			dir;

    cols	= frame::count_columns (gFrame, &gut);
    wlog ("", "Frame : %d columns, gutter %f\n", cols, gut);

    cols	= page::count_columns (page::get (gFrame), &gut, &dir);
    wlog ("", "Page %d : %d columns, gutter %f, direection %d\n", page::get (gFrame), cols, gut, dir);

    return 0;
}

Version 1.3.1 (20. Jan. 2006)

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

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

priint:comet InDesign® Plug-Ins, comet_pdf

create_columns
comet.CFrame.getColumnCount

static int delete_textframe(ItemRef itemRef)

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

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

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

int main ()
{
    char			path[4096];
    int			ipos		= -1;
    ItemRef		parent	= item::alloc ();

    strcpy (path, "$DESKTOP/clara.JPG");
    if (frame::isinline (gFrame))
    {
        ipos	= frame::inlinepos (gFrame);
        frame::textframe (gFrame, parent);
    }

    if (file::exists (path))	frame::image (gFrame, path);
    else frame::remove (gFrame);

    if (item::defined (parent))
    {
        // remove case cap
        // fit textframe
        textmodel::initialchar (parent, ipos, 0, 0);
        frame::fit (parent);
        frame::fit (parent);
    }

    return 0;
}


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

static int remove(ItemRef itemRef)

Synonymous for delete_textframe.

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

Select a document frame.

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

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

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


priint:comet InDesign® Plug-Ins

static int rectangle(ItemRef)

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

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


priint:comet InDesign® Plug-Ins, comet_pdf
resize

static int oval(ItemRef)

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

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


priint:comet InDesign® Plug-Ins
resize

static int polygon(ItemRef itemRef, int sides)

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

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


priint:comet InDesign® Plug-Ins
resize

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

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

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


priint:comet InDesign® Plug-Ins
resize

static int spline(ItemRef frameRef, ...)

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

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


priint:comet InDesign® Plug-Ins

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

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

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

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

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

kRefPointTopLeft
kRefPointTopCenter
kRefPointTopRight
kRefPointLeftCenter
kRefPointCenter
kRefPointRightCenter
kRefPointBottomLeft
kRefPointBottomCenter
kRefPointBottomRight

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

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

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

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

float	w, h;
ItemRef	itemRef = ... 

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

seit v3.4 R5220 (3. Mar 20124)

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

comet.CFrame.fit
fit
fit_image

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

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

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

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

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

kRefPointTopLeft
kRefPointTopCenter
kRefPointTopRight
kRefPointLeftCenter
kRefPointCenter
kRefPointRightCenter
kRefPointBottomLeft
kRefPointBottomCenter
kRefPointBottomRight

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

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

float	w, h;
ItemRef	itemRef = ... 

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

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

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CFrame.fit
fit_better
fit_image
item::fitframe

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

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

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

  

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

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

  

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

 

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

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

  

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

 

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

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

  

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

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

  

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

 

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

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

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

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

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

4 : Center content in frame

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

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

Methods 3, 4: Parameter is ignored

Method 5:
Image Position. If the parameter is omitted, then - if the image has already been placed by the Comet - the last Comet placement for this image is restored.
size float 0.0 Image placement size of bounding box for image, see here

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

-1.0 : Any scaling > 0.0 allwoed

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

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

priint:comet InDesign® Plug-Ins, comet_pdf

fit_better
is_graphicframe
set_fitting_options
comet.CFrame.fitImage

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

Set the frames fitting options. Supported since CS4.

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

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

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

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

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

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

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

int main ()
{
    Rect			crop		= rect::alloc (12.0, 13.0, 14.0, 15.0);

    frame::set_fitting_options (gFrame, kRefPointLeftCenter, 2, crop, 1, 1);
    return 0;
}

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

priint:comet InDesign® Plug-Ins, comet_pdf

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

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

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

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

0 : Ohne
1 : Inhalt an Rahmen anpassen
2 : Inhalt proportional anpassen
3 : Rahmen proportional füllen
crop Rect 0 On successful return the rectangle contains the crop amounts
autoFit int* 0 On successful return the address contains the autoFit value. Since this behavior was invoked in CS5, versions prior CS5 always returning 0 here.
#include "internal/types.h"
#include "internal/types.h"

int main ()
{
    int 	refPoint;
    int		fitting;
    Rect	crop = rect::alloc ();
    int		autoFit;

    frame::get_fitting_options (gFrame, &refPoint, &fitting, crop, &autoFit);
    wlog ("", "Frame %d\n", item::getint (gFrame));
    wlog ("", "	%d %d [%f, %f, %f, %f], %d\n",
     		refPoint,
     		fitting,
     		rect::left (crop),
     		rect::top (crop),
     		rect::right (crop),
     		rect::bottom (crop),
     		autoFit);
    return 0;
}

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

priint:comet InDesign® Plug-Ins, comet_pdf

static int clear_fitting_options(ItemRef frameRef)

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

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

Version 3.2.1 R2330, 7.März 2011

priint:comet InDesign® Plug-Ins, comet_pdf

static int apply_fitting_options(ItemRef frameRef)

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

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

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

priint:comet InDesign® Plug-Ins, comet_pdf

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

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

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

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

< 0 append
auto_load int on Should the text placeholders in the TaggedText be activated?
flags int 0 Instructions for preparing TaggedText.

0 : Off
2 : Fix parastyles of all cells
4 : Fix parastyles of complete text
8 : Check tables
16 : Replace <in> tags by <w2inline> tags, (since v4.1 R21213)
32 : Repair hyperlinks (since v4.1 R22201)

Please note:
  • For normal text, the parameter has no meaning.
  • If the option Plug-Ins -> Comet -> Read PlaceHolders from TaggedText is disabled, the flags 2, 4 and 16 do not have any meaning and are ignored.
  • In comet_pdf the flags 2 and 4 have no meaning, missing or empty paragraph styles are always calculated and used here.
  • \As of v4.1.6 R25777 the w2inline replacement always is done automatically. Since w2inline is a character attribute and can only be evaluated if a paragraph style is defined, the paragraphs will also be corrected in all non-empty table cells.} Changes to your TaggedText are not required for this.

Insert at position 2 

frame::insert (frameRef, text, 2)

Append 

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

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

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

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

Recursive safe inserting text in a frame.

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

v3.4 R4650, 25.10.2013

priint:comet InDesign® Plug-Ins

insert
comet.CFrame.setText

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

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

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

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Text frame into which the text is to be inserted
String or char* tt - text to be inserted (can also be TaggedText)
auto_load int 1 Should the text placeholders in the TaggedText be activated?
flags int 0 Instructions for preparing TaggedText.

0 : Off
2 : Fix parastyles of all cells
4 : Fix parastyles of complete text
8 : Check tables
16 : Replace <in> tags by <w2inline> tags, (since v4.1 R21213)
32 : Repair hyperlinks (since v4.1 R22201)

Please note:
  • For normal text, the parameter has no meaning.
  • If the option Plug-Ins -> Comet -> Read PlaceHolders from TaggedText is disabled, the flags 2, 4 and 16 do not have any meaning and are ignored.
  • In comet_pdf the flags 2 and 4 have no meaning, missing or empty paragraph styles are always calculated and used here.
  • \As of v4.1.6 R25777 the w2inline replacement always is done automatically. Since w2inline is a character attribute and can only be evaluated if a paragraph style is defined, the paragraphs will also be corrected in all non-empty table cells.} Changes to your TaggedText are not required for this. 
frame::append (frameRef, text, 0);

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

priint:comet InDesign® Plug-Ins, comet_pdf

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

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

Recursive safe appending text to a frame.

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

v3.4 R4650, 25.10.2013

priint:comet InDesign® Plug-Ins, comet_pdf

append
prefs::set_logstate
comet.CFrame.setText

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

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

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

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

kEnd : End of text, in placeholder scripts up to the end of the placeholder
auto_load int 1 Should the text placeholders in the TaggedText be activated?
flags int 0 Instructions for preparing TaggedText.

0 : Off
2 : Fix parastyles of all cells
4 : Fix parastyles of complete text
8 : Check tables
16 : Replace <in> tags by <w2inline> tags, (since v4.1 R21213)
32 : Repair hyperlinks (since v4.1 R22201)

Please note:
  • For normal text, the parameter has no meaning.
  • If the option Plug-Ins -> Comet -> Read PlaceHolders from TaggedText is disabled, the flags 2, 4 and 16 do not have any meaning and are ignored.
  • In comet_pdf the flags 2 and 4 have no meaning, missing or empty paragraph styles are always calculated and used here.
  • \As of v4.1.6 R25777 the w2inline replacement always is done automatically. Since w2inline is a character attribute and can only be evaluated if a paragraph style is defined, the paragraphs will also be corrected in all non-empty table cells.} Changes to your TaggedText are not required for this.
#include "internal/text.h"

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

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

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

//
// Script 1 : Using textmodel::replace and textmodel::insert
//
#include "internal/types.h"
#include "internal/text.h"

int main ()
{
    int			T = table::alloc ();

    if (!T) 		return;

    textmodel::replace ("<CharStyle:MyStyle1>A<0x00FC>C", 0, kEnd);

    table::create (T, gFrame, 2, 2, kEnd, 0, 20.0, 20.0);
    table::release (T);

    textmodel::insert ("XXX", kEnd);

    return 0;

}

//
// Script 2: Using frame::replace and frame::insert
// You get the same result as with script 1.
// But take care to use the current placeholder
// positions and lengths.
//
#include "internal/types.h"
#include "internal/text.h"

int main ()
{
    int			T = table::alloc ();

    if (!T) 		return;

    frame::replace (gFrame, "<CharStyle:MyStyle1>A<0x00FC>C", textmodel::start ());

    table::create (T, gFrame, 2, 2, kEnd, 0, 20.0, 20.0);
    table::release (T);

    frame::insert (gFrame, "XXX", textmodel::start () + textmodel::length ());

    return 0;
}

//
// Script 3 : Not working!
// Using frame::replace_all instead of frame::replace, the script will do wrong things:
// The current placeholder is replaced by the trailing text - but the placeholder is removed.
// Inserting the table at kEnd therfore now means : At the end of the whole text!
// Because you have no placeholder, textmodel::start and textmodel::length are both 0.
// The text XXX therefor is inserted at the beginning of the text :-(
//
#include "internal/types.h"
#include "internal/text.h"

int main ()
{
    int			T = table::alloc ();

    if (!T) 		return;

    frame::replace_all (gFrame, "%!TT<CharStyle:MyStyle1>A<0x00FC>C", textmodel::start (), textmodel::length ());

    table::create (T, gFrame, 2, 2, kEnd, 0, 20.0, 20.0);
    table::release (T);

    frame::insert (gFrame, "XXX", textmodel::start () + textmodel::length ());

    return 0;
}

//
// Script 4 : Panel script
// The complete text of the current frame is replaced!
//
#include "internal/types.h"
#include "internal/text.h"

int main ()
{
    int			T = table::alloc ();

    if (!T) 		return;

    frame::replace_all (gFrame, "%!TT<CharStyle:MyStyle1>A<0x00FC>C", 0, kEnd);

    table::create (T, gFrame, 2, 2, kEnd, 0, 20.0, 20.0);
    table::release (T);

    frame::insert (gFrame, "XXX", kEnd);

    return 0;
}

Replace position 2-5 

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

Replace position 2 

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

Replace everything 

frame::replace (frameRef, text);

Like frame::append 

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

Like frame::insert 

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

Replace the current text selection 

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

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

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

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

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

Recursive safe replacing text in a frame.

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

v3.4 R4650, 25.10.2013

priint:comet InDesign® Plug-Ins, comet_pdf

replace
comet.CFrame.setText

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

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

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

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

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

Name Type Default Description
Return int   0 or ErrorCode
frameRef ItemRef - Text frame in which the text is to be inserted
String or char* tt - text to be inserted (can also be TaggedText)
position int 0 text-relative insert position or kEnd, kSelection
delete_len int 0 Number of the character or kEnd to be deleted
auto_load int 1 Should the text placeholders in the TaggedText be activated?
flags int 0 Instructions for preparing TaggedText.

0 : Off
2 : Fix parastyles of all cells
4 : Fix parastyles of complete text
8 : Check tables
16 : Replace <in> tags by <w2inline> tags, (since v4.1 R21213)
32 : Repair hyperlinks (since v4.1 R22201)

Please note:
  • For normal text, the parameter has no meaning.
  • If the option Plug-Ins -> Comet -> Read PlaceHolders from TaggedText is disabled, the flags 2, 4 and 16 do not have any meaning and are ignored.
  • In comet_pdf the flags 2 and 4 have no meaning, missing or empty paragraph styles are always calculated and used here.
  • \As of v4.1.6 R25777 the w2inline replacement always is done automatically. Since w2inline is a character attribute and can only be evaluated if a paragraph style is defined, the paragraphs will also be corrected in all non-empty table cells.} Changes to your TaggedText are not required for this.
#include "internal/text.h"

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

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

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

//
// Script 1 : Using textmodel::replace and textmodel::insert
//
#include "internal/types.h"
#include "internal/text.h"

int main ()
{
    int			T = table::alloc ();

    if (!T) 	return;

    textmodel::replace ("<CharStyle:MyStyle1>A<0x00FC>C", 0, kEnd);

    table::create (T, gFrame, 2, 2, kEnd, 0, 20.0, 20.0);
    table::release (T);

    textmodel::insert ("XXX", kEnd);

    return 0;

}

//
// Script 2: Using frame::replace and frame::insert
// You get the same result as with script 1.
// But take care to use the current placeholder
// positions and lengths.
//
#include "internal/types.h"
#include "internal/text.h"

int main ()
{
    int			T = table::alloc ();

    if (!T) 	return;

    frame::replace (gFrame, "<CharStyle:MyStyle1>A<0x00FC>C", textmodel::start ());

    table::create (T, gFrame, 2, 2, kEnd, 0, 20.0, 20.0);
    table::release (T);

    frame::insert (gFrame, "XXX", textmodel::start () + textmodel::length ());

    return 0;
}

//
// Script 3 : Not working!
// Using frame::replace_all instead of frame::replace, the script will do wrong things:
// The current placeholder is replaced by the trailing text - but the placeholder is removed.
// Inserting the table at kEnd therfore now means : At the end of the whole text!
// Because you have no placeholder, textmodel::start and textmodel::length are both 0.
// The text XXX therefor is inserted at the beginning of the text :-(
//
#include "internal/types.h"
#include "internal/text.h"

int main ()
{
    int			T = table::alloc ();

    if (!T) 	return;

    frame::replace_all (gFrame, "%!TT<CharStyle:MyStyle1>A<0x00FC>C", textmodel::start (), textmodel::length ());

    table::create (T, gFrame, 2, 2, kEnd, 0, 20.0, 20.0);
    table::release (T);

    frame::insert (gFrame, "XXX", textmodel::start () + textmodel::length ());

    return 0;
}

//
// Script 4 : Panel script
// The complete text of the current frame is replaced!
//
#include "internal/types.h"
#include "internal/text.h"

int main ()
{
    int			T = table::alloc ();

    if (!T) 	return;

    frame::replace_all (gFrame, "%!TT<CharStyle:MyStyle1>A<0x00FC>C", 0, kEnd);

    table::create (T, gFrame, 2, 2, kEnd, 0, 20.0, 20.0);
    table::release (T);

    frame::insert (gFrame, "XXX", kEnd);

    return 0;
}

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

priint:comet InDesign® Plug-Ins, comet_pdf

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

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

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

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

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

Version 2.1, R1401, 29.06.2009

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

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

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

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

Version 2.1, R1401, 29.06.2009

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

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

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

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

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

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

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

static int link(ItemRef from, ItemRef to)

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

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

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

Version 2.1, R1401, 29.06.2009

priint:comet InDesign® Plug-Ins, comet_pdf

static int get_link(ItemRef frameRef, ItemRef toRef)

Find the next text frame in a text frame chain.

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

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

#include "internal/text.h"
#include "internal/types.h"

int main()
{
    ItemRef		succ	= item::alloc ();
    int			succRes	= frame::get_link (gFrame, succ);
    int			tpos	= frame::get_textpos (gFrame);

    if (succRes == 0 && !frame::is_valid (succ))
    {
        textmodel::justify_reset (gFrame, tpos);
    }

    textmodel::justify (gFrame, 0, kFrameEnd);

    return 0;
}

Version 2.1, R1401, 29.06.2009

priint:comet InDesign® Plug-Ins, comet_pdf

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

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

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

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

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

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

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

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

#include "internal/text.h"
#include "internal/types.h"

int main()
{
    ItemRef		succ		= item::alloc ();
    int			succRes		= frame::get_link (gFrame, succ);
    int			tpos		= frame::get_textpos (gFrame);

    if (succRes == 0	 && !frame::is_valid (succ))
    {
        textmodel::justify_reset (gFrame, tpos);
    }

    textmodel::justify (gFrame, 0, kFrameEnd);

    return 0;
}

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

priint:comet InDesign® Plug-Ins

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

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

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

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

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

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

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

-1.0 : Leave unchanged

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

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

comet.CPageItem.setFillColor

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

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

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

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

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

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

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

-1.0 : Leave unchanged

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

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

comet.CPageItem.setFillColor

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

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

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

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

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

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

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

-1.0 : Leave unchanged

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

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

comet.CPageItem.setFillColor

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

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

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

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

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

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

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

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

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

priint:comet InDesign® Plug-Ins, comet_pdf

get_opacity
set_blending
get_blending
set_overprint
get_overprint

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

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

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

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

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

-1 : Keep untouched

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

-1 : Keep untouched

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

char * what2str (int what, char * ws)
{
    if (what == kBlendingBasic) strcpy (ws, "Basic");
    else if (what == kBlendingStroke) strcpy (ws, "Stroke");
    else if (what == kBlendingFill) strcpy (ws, "Fill");
    else if (what == kBlendingContent) strcpy (ws, "Content");
    else sprintf (ws, "Blend %d", what);

    return ws;
}

int w_blendings (ItemRef fr, char * mess)
{
    float		opac;
    int			blendmode;
    int			isolation;
    int			knockout;
    int			what;
    char		ws[255];

    wlog ("", "Frame %d, %s\n", item::getint (gFrame), mess);

    for (what = kBlendingBasic; what <= kBlendingContent; what++)
    {
        opac = frame::get_blending (gFrame, what, &blendmode, &isolation, &knockout);
        wlog ("", "     %s\t%f\t%d\t%d\t%d\n",
         	what2str (what, ws),
         	opac,
         	blendmode,
         	isolation,
         	knockout);
    }

    wlog ("", "\n");
    return 0;
}

int change_blending (ItemRef fr, int what, float opacity, int blendmode, int isolation, int knockout)
{
    int			result 	= frame::set_blending (fr, what, opacity, blendmode, isolation, knockout);
    char		mess	[512];
    char		ws		[255];

    sprintf (mess, "%s changed to (%f, %d, %d, %d)",
     	what2str (what, ws),
     	opacity,
     	blendmode,
     	isolation,
     	knockout);
    w_blendings (fr, mess);
    return result;
}

int w_overprints (ItemRef fr, char * mess)
{
    wlog ("", "%s :: frame %d overprints : fill %d, stroke %d, gap %d\n",
     	mess,
     	item::getint (fr),
     	frame::get_overprint (fr, kOverprintFill),
     	frame::get_overprint (fr, kOverprintStroke),
     	frame::get_overprint (fr, kOverprintGap));
    return 0;
}

int main ()
{
    w_blendings (gFrame, "Original");

    change_blending (gFrame, kBlendingStroke,	30.0, 3, 1, 1);
    change_blending (gFrame, kBlendingFill,		40.0, 4, 1, 0);
    change_blending (gFrame, kBlendingContent,	50.0, 5, 1, 0);
    change_blending (gFrame, kBlendingBasic,	60.0, 6, 1, 0);

    w_overprints (gFrame, "Before");
    frame::set_overprint (gFrame, kOverprintFill, 0);
    frame::set_overprint (gFrame, kOverprintStroke, 1);
    frame::set_overprint (gFrame, kOverprintGap, 1);
    w_overprints (gFrame, "After");

    return 0;
}

v4.0.5 R9720, 4. Dec 2015

priint:comet InDesign® Plug-Ins, comet_pdf

get_blending
set_overprint
get_overprint

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

Get opacity and blend mode of frames.

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

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

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

0 : No
1 : Yes

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

0 : No
1 : Yes

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

see set_blending

v4.0.5 R9720, 4. Dec 2015

priint:comet InDesign® Plug-Ins, comet_pdf

get_blending
set_overprint
get_overprint

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

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

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

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

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

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

See get_overprint

v4.0.5 R9720, 4. Dec 2015

priint:comet InDesign® Plug-Ins, comet_pdf

get_blending
set_blending
get_overprint
comet.CPageItem.setOverprint

static int get_overprint(ItemRef frameRef, int what)

Get the overprint of a frame.

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

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

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

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

See set_overprint

v4.0.5 R9720, 4. Dez 2015

priint:comet InDesign® Plug-Ins, comet_pdf

get_blending
set_blending
set_overprint
comet.CPageItem.getOverprint

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

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

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

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

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

-1.0 ignore
overPrint int -1 Overprint background?

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

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

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

-1.0 ignore
gapOverprint int -1 Overprint gap background?

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

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

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

priint:comet InDesign® Plug-Ins, comet_pdf
comet.CPageItem.setStroke

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

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

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

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

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

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

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

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

The parameters from tint are available from version 1.0.20.

priint:comet InDesign® Plug-Ins, comet_pdf
comet.CPageItem.setStroke

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

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

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

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

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

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

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

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

The parameters from tint are available from version 1.0.20.

priint:comet InDesign® Plug-Ins, comet_pdf
comet.CPageItem.setStroke

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

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

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

    frame::get_stroke (
     	gFrame,
     	&type,
     	&width, &viswidth,
     	&overprint, &gapoverprint,
     	&align,
     	&miter);

    wlog ("", "# Stroke of frame %d\n", item::getint (gFrame));
    wlog ("", "       type		: %d\n", type);
    wlog ("", "       width		: %f (%f)\n", width, viswidth);
    wlog ("", "       overprint	: %d (%d)\n", overprint, gapoverprint);
    wlog ("", "       align		: %d\n", align);
    wlog ("", "       miter		: %f\n", miter);

    frame::get_stroke_color (
     	gFrame,
     	0,
     	colname,
     	&colspace,
     	&c1, &c2, &c3, &c4,
     	&tint);
    wlog ("", "       color		: %s (%f, %f, %f, %f), %f%%\n", colname, c1, c2, c3, c4, tint);

    frame::get_stroke_color (
     	gFrame,
     	1,
     	colname,
     	&colspace,
     	&c1, &c2, &c3, &c4,
     	&tint);
    wlog ("", "       gap-color	: %s (%f, %f, %f, %f), %f%%\n", colname, c1, c2, c3, c4, tint);

    return 0;
}

Version 3.1 R2137, 20.09.2010

priint:comet InDesign® Plug-Ins, comet_pdf

stroke
get_stroke_color

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

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

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

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

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

#include "internal/types.h"

int main ()
{
    char		colName[256];
    int			colSpace;
    float		c1, c2, c3, c4, tint;

    if (frame::get_stroke_color (0,0, colName,&colSpace,&c1,&c2,&c3,&c4,&tint) == 0)
    {
        if (colSpace == kRGB)
        {
            showmessage (
             	"Color Name : %s\nR : %f\nG : %f\nB : %f\nTint : %f\n",
             	colName,
             	c1, c2, c3, tint);
        }
        else if (colSpace == kCMYK)
        {
            showmessage (
             	"Color Name : %s\nC : %f\nM : %f\nY : %f\nK : %f\nTint : %f\n",
             	colName,
             	c1, c2, c3, c4, tint);
        }
        else if (colSpace == kLab)
        {
            showmessage (
             	"Color Name : %s\nL : %f\na : %f\nb : %f\nTint : %f\n",
             	colName,
             	c1, c2, c3, tint);
        }
        else
        {
            showmessage ("Unknown color space");
        }
    }
    else
    {
        showmessage ("Color could not be determined.");
    }

    return 0;
}

Version 3.1 R2137, 20.09.2010

priint:comet InDesign® Plug-Ins, comet_pdf

get_color
get_stroke

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

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

The following line ends (arrows) are supported:

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

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

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

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

0 : Ignore return value

v4.2 R31404, 15. Aug 2022

priint:comet InDesign® Plug-Ins, comet_pdf

set_lineends
get_type

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

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

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

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

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

-1 : Leave unchanged

v4.2 R31404, 15. Aug 2022

priint:comet InDesign® Plug-Ins, comet_pdf

get_lineends
get_type

static int noshadow(ItemRef frameRef)

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

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

v3.0

priint:comet InDesign® Plug-Ins

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

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

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

v3.0

priint:comet InDesign® Plug-Ins

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

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

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

v3.0

priint:comet InDesign® Plug-Ins

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

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

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

v3.0

priint:comet InDesign® Plug-Ins

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

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

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

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

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



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





priint:comet InDesign® Plug-Ins







textmodel::store
frame::restore_text








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



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







Name
Type
Default
Description





Return

int
 

0 oder ErrorCode






start

int
-

Start position, from which the text is to be stored

kSelection Current text selection

>= 0 Text position. Values larger than the text length are placed at the end of the text

otherwise : text start






len

int
-

Length of the text which is to be stored

kEnd Copy to end of text
<=0 : Save empty text

Is start == kSelection the length specification has no significance.






ID

int
-

ID in the target table. The text component will be set up as required.

<= 0 : Independently ascertain the next free ID






macroID

int*
0

ID of the set up or changed template. In case of an errorl (return != 0) the variable is given the value 0.






dbc

DBC
0

Target database. Is this information  is absent, the current database connection will be used.






table

String or char*
0

Name of the target table. The name is only relevant where exporting to the database. Where exporting in XML files and
to SOAP server the entries and inserted to the file pageitems.xml and the data and the
preview are filed in sub-files in the data folder pageitems.

If the table name is empty (0 or ""), the database table will be used as the target table
pageitems and the data stored in pageitems.data. In pageitems.preview
a screenshot of the template will be stored.






data_attr

String or char*
0

The attribute is only relevant with export to databases (not for XML or SOAP) and a table name not equal to 0, ""
or "pageitems"
and defines the attribute of the target table,
in which the result is to be written. The
attribute must be of the type BLOB and may not be called TEXT..






prv_attr

String or char*
0

The attribute  is only relevant with export to databases (not for XML or SOAP) and a table name not equal to 0, ""
or "pageitems"
and defines the attribute of the target table, in which the screenshot  which the result is to be written. The
attribute must be of the type BLOB and may not be called TEXT..






useOldStyle

int
1

since version 1.34 R 343 From this release on parts of linked frames are exported too.
1 : use only the home frame
0 : Be care of linked frames too






macroName

String or char*
0

name of template. Used only if table is empty or pageitems





  #include "internal/text.h"




Save the current text selection in a new template.



int main ()
{
    int		res;
    int		macroID;

    res = frame::store_macro (
     	gFrame,	// Current frame
     	-2, 0,	// Current text selection
     	-1,		// Store new template
     	¯oID);	// ID of the stored template

    if (res == 0 && macroID != 0)
     	showmessage ("Template %d stored", macroID);
    else
     	showmessage ("Error %d", res);

    return 0;
}



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





priint:comet InDesign® Plug-Ins, comet_pdf







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








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



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








Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Text frame the contents of which are to be changed






start

int
-

Start position, from which the existing text is to be overwritten

kSelection Current text selection

>= 0 Text position. Values larger than the text length are place at the end of the
text

otherwise : text start






len

int
-

Length of the text which is to be overwritten

kEnd Overwrite to the end of the text
<=0 : Insert upon start

Is start == kSelection the length specification has no significance.






dbc

DBC
-

Database where the macro is stored


0 : Current data connection


The specification is used in ODBC data connections only.
In XML offline and SOAP/PubServerver connections the template storage is always used.






attr

String oder char*
-

Attribute name in the table of macros. The attribute must be of type BLOB and must not be called TEXT.


0 or "" : "data"


The specification is used in ODBC data connections only.
In XML offline and SOAP/PubServerver connections the template storage is always used.






table

String oder char*
-

Name of the table with the macros.


0 or "" : "pageitems"


The specification is used in ODBC data connections only.
In XML offline and SOAP/PubServerver connections the template storage is always used.






ID

int
-

ID in the table of macros. In XML offline and SOAP/PubServerver connections, use the template ID here.






autoLoad

int
1

Should placeholders, which are located in the inserted text, be set up again?

0 : Placeholder not to be loaded

otherwise :Load placeholders






inserted

int*
0

How many characters have been inserted in the text? The variable only then has a purposeful
value, if the function is ended without error.





  #include "internal/text.h"




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




Version 1.1.4

The parameter autoLoad and inserted are implemented since Version 1.1.7, January 2005.

comet_pdf since v4.2 R32720, 14. Apr 2023





priint:comet InDesign® Plug-Ins ,comet_pdf







frame::store_text
textmodel::restore








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



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







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Text frame in which the text template are to be inserted.






start

int
-

Start position, from which the text is to be inserted

kSelection Current text selection

>= 0 Text position. Values larger than the text length are place at the end of the text

otherwise : text start






len

int
-

Length of the text which is to be removed prior to the insertion. As the text is deleted
all floating frames, which are connected with parts of the deleted text, are likewise deleted.

kEnd Delete to end of the text
<=0 : Not an empty text

Is start == kSelection the length specification has no significance.






ID

int
-

ID in the table of macros. In XML offline and SOAP/PubServerver connections, use the template ID here.






autoLoad

int
0

Should the placeholders in the text be loaded again following the insertion of the text?

0 : do not load

Otherwise : load






inserted_len

int*
0

How many characters were inserted in the text? The variable only has meaningful value if the function has ended without errors.






dbc

DBC
-

Database where the macro is stored


0 : Current data connection


The specification is used in ODBC data connections only.
In XML offline and SOAP/PubServerver connections the template storage is always used.






attr

String oder char*
-

Attribute name in the table of macros. The attribute must be of type BLOB and must not be called TEXT.


0 or "" : "data"


The specification is used in ODBC data connections only.
In XML offline and SOAP/PubServerver connections the template storage is always used.






table

String oder char*
-

Name of the table with the macros.


0 or "" : "pageitems"


The specification is used in ODBC data connections only.
In XML offline and SOAP/PubServerver connections the template storage is always used.





  #include "internal/text.h"




Insert a text template.



int main ()
{
    int		result;
    int		inserted;

    result = frame::insert_macro (
     		gFrame,		// Current frame
     		-2, 0,		// Current text selection
     		23,			// Text template ID
     		1,			// Load placeholder
     		&inserted);	// Number of new characters

    if (result == 0)
     		showmessage ("%d characters inserted", inserted);
    else
     		showmessage ("Error : %s.", serror (result));

    return 0;
}



Version 1.2.1 (11 August 2005)





priint:comet InDesign® Plug-Ins







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








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



 Ascertain the path of the image of a Graphic Frame.







Name
Type
Default
Description





Return

char*
 

0 : Image path could not been ascertained

Otherwise the parameter path of the function will be returned






frameRef

ItemRef
-

Reference to a valid Graphic Frame of the document






path

String or char*
-

Reserved memory for the result path






deepDive

int
0

You can include Graphic Frames AND its image into an other frame (I do NOT describe, how). In my eyes this is an InDesign® bug.
How ever, the function shall return an image in this situation too. Set deepDive to 1 to let the function search for an image path
inside the frames hierarchy too.

   


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


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

Ignored by Illustrator.










int main ()
{
    char		path[4096];

    if (frame::image_getpath (gFrame, path))
    {
        showmessage (path);
    }
    else showmessage ("No image frame or no image");

    return 0;
}



Version 1.1.6

Parameter deepDive since v3.3 R2812, 01.03.2012





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



comet.CFrame.getImage








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



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







Name
Type
Default
Description





Return

int
 

0 : Image position could be ascertained

Error status : The frame is not a Graphic Frame or contains no graphic






frameRef

ItemRef
-

Reference to a valid Graphic Frame of the document






x

float*
0

Return variable for the spacing from the left side of the Graphic Frame. The specification is given in points.

The parameter may be 0.






y

float*
0

Return variable for the spacing from the left side of the Graphic Frame. The specification is given in points.

The parameter may be 0.






boundsKind

int
0

Get position relative to this bounds:


0 : outer stroke path

1 : path bounds ("blue" frame)









Does the specified frame contain an image?



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





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



int main ()
{
    char		path[4096];
    float		x, y, width, height, scaleX, scaleY, rotat, skew;
    char		fmt[8000];

    strcpy (fmt, "%s\r Position : %.6f x %.6f");
    strcat (fmt, "\r Size : %.6f x %.6f");
    strcat (fmt, "\r Scaling : %.6f x %.6f");
    strcat (fmt, "\r Rotation : %.6f");
    strcat (fmt, "\r Skew : %.6f");

    frame::image_getpath (gFrame, path);
    frame::image_getpos (gFrame, &x, &y, 1);
    frame::image_getsize (gFrame, &width, &height);
    frame::image_getscale (gFrame, &scaleX, &scaleY);
    frame::image_getrotation (gFrame, &rotat);
    frame::image_getskew (gFrame, &skew);

    showmessage (fmt,
     	path,
     	x, y,
     	width, height,
     	scaleX, scaleY,
     	rotat, skew);

    return 0;
}



Version 1.1.6

boundsKind since v3.4 R5126, 24. Jan 2014





priint:comet InDesign® Plug-Ins, comet_pdf









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



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



The function is equal to image::clippath.







Name
Type
Default
Description





Return

int
 

0 : Bounding box caclulated

Error code : no Graphic Frame, no image, or no clip path






frameRef

ItemRef
-

valid document frame






l

float*
0

left






t

float*
0

top






r

float*
0

right






b

float*
0

bottom







Version 1.1.6





priint:comet InDesign® Plug-Ins, comet_pdf











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



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







Name
Type
Default
Description





Return

int
 

0 : Image position could be ascertained

Error status : The frame is not a Graphic Frame or contains no image






frameRef

ItemRef
-

Reference to a valid Graphic Frame of the document






w

float*
0

Return variable for width of the Graphic Frame. The specification is given in points.

The parameter may be 0.






h

float*
0

Return variable for the height of the Graphic Frame. The specification is given in points.

The parameter may be 0.






bboxType

int
0

0 : Size of the bounding box of the (possible rotated) image

1 : Current size of image frame









See example for image_getpos.




Version 1.1.6

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





priint:comet InDesign® Plug-Ins, comet_pdf



comet.CFrame.getImageSize








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



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


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








Name
Type
Default
Description





Return

int
 

0 : Image scaling could be ascertained

Error status : The frame is not a Graphic Frame of contains no image






frameRef

ItemRef
-

Reference to a valid Graphic Frame of the document






x

float*
0

Return variable for the scaling in X direction (100% corresponds to 1.0).

The parameter may be 0.






y

float*
0

Return variable for the scaling in Y direction (100% corresponds to 1.0).

The parameter may be 0.









See example for image_getpos.




Version 1.1.6





priint:comet InDesign® Plug-Ins, comet_pdf



comet.CFrame.getImageScale








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



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








Name
Type
Default
Description





Return

int
 

0 : Rotatio degree could be ascertained

Error status : The frame is not a Graphic Frame of contains no image






frameRef

ItemRef
-

Reference to a valid Graphic Frame of the document






x

float*
0

Drehwinkel. Die Angaben sind analog den Angaben in InDesign® .

Der Parameter darf 0 sein.









See example for image_getpos.




Version 1.1.6





priint:comet InDesign® Plug-Ins, comet_pdf



comet.CFrame.getImageRotation








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



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


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







Name
Type
Default
Description





Return

int
 

0 : Skew degree could be ascertained

Error status : The frame is not a Graphic Frame of contains no image






frameRef

ItemRef
-

Reference to a valid Graphic Frame of the document






x

float*
0

Skew degree. The specification are analagous to the specification in InDesign® .

The parameter may be 0 .









See example for image_getpos.




Version 1.1.6





priint:comet InDesign® Plug-Ins, comet_pdf



comet.CFrame.getImageSkew








static   int image_blackcolor(ItemRef frameRef, char*  colorName)



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




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







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Target frame






colorName

String or char*
-

Name of the color










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



Version 2.1 R 913, 22. Aug. 2008





priint:comet InDesign® Plug-Ins







image_blackcolor_rgb
image_blackcolor_cmyk







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



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







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Target frame






r, g, b

int
-

color values (0-255)










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



Version 2.1 R 913, 22. Aug. 2008





priint:comet InDesign® Plug-Ins







image_blackcolor
image_blackcolor_cmyk








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



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







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Target frame






c, m, y, k

int
-

color values (0.0 - 1.0)







Version 2.1 R 913, 22. Aug. 2008





priint:comet InDesign® Plug-Ins







image_blackcolor
image_blackcolor_rgb







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



Place a file into a frame.




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




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




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





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





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



"CC Libraries: Libname/Imagename"




File aliases are allowed for library names here.




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




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







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Frame in which the image is to be inserted






path

String oder char*
-

Image address


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


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


CC Libraries : Specification of the image in the format "CC Libraries: Libname/Imagename".
File aliases are allowed for the library names. In this case only the name part of the path is used.






alignment

int
kMiddle

see image positions







boundingBox

float
kFitBigContentProp

Image size in points


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


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


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







⇨ Photoshop  Clipping Path






pathindex

int
0

0-based index of clipping path


kIgnoreClipping : Ignore clip setting

kResetClipping : Reset any existing clipping.

-1 : Use pathname

≥ 0 : 0-based clipping path index. Values > 0 are ignored by comet_pdf here. Comet_pdf uses the path defined by \span[src]{pathname instead.}






pathname

String or char*
""

Name of clipping path


Values ignored by InDesign® if the path is defined by its index already (pathindex ≥ 0).






⇨ Properties for clipping. Also used for alpha channels.






flags

int
0

How to clip the image? T%he parameter is a bit field, so values can be added.


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

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

kRestrictToFrameFlag


Value is ignored by comet_pdf.






cliptoFrame

int
0

Use the the clipping path as the frames path?


0 : Keep old frame 

1 : Change frame






tolerance

float
0.0

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


The parameter is not applied by Indesign® Server and comet_pdf.






minPathSize

float
0.0

subpaths smaller than the minPathSize will be deleted.


The parameter is not applied by Indesign® Server and comet_pdf.






inset

float
0.0

How far to inset the path


The parameter is not applied by Indesign® Server and comet_pdf.






⇨ Alpha Channel






alphaIndex

int
0

0-based index of channel, see image::alpha_channel_index


kIgnoreClipping : Leave the alpha channel unchanged.

kResetClipping : Reset alpha channel when inserting the image.

-1 : Use the value of alphaChannel
≥ 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 if the channel is defined by its index already (e.g. alphaIndex ≥ 0).






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.
Alternatively, you can also add the value kAllowHolesFlag to src{flags}.






⇨ Update Flags






updateFlags

int 
0

For Web-Images Only


16 : If the local image file already exists, it is used without further checkings.





  #include "internal/types.h"





document::folder (path);
strcat (path, "/Bilder/Echinops/banaticus.JPG");
frame::image (frame, path, 5, 100.0);





Insert an image and apply its first alpha channel



#include "internal/types.h"

int main ()
{
    int		result;

    result = frame::image (
     	gFrame,
     	"your path",
     	kPlaceCentered,
     	kFitBigContentProp,
     	kIgnoreClipping, 0, 0,
     	0, 0.0, 0.0, 0.0,
     	0, 0);
    wlog ("", "Result of placing image : %d (%s).\n", result, serror (result));
    return 0;
}





The following example shows how to set import options for images on script side. More Import Options
can be found here.

Please note that you have to get the current setting for pdfCrop as string here. But the value obtained
is an enumeration type and must therefore be specified as int when resetting!



#include "internal/types.h"

int main ()
{
    char		oldCrop 	[256];
    char		resetCmd 	[512];
    ItemRef  	lk 			= item::alloc ();

    run_javascript ("function main () {return app.pdfPlacePreferences.pdfCrop;} main ();", 0, 1, 0, kString, oldCrop);
    run_javascript ("app.pdfPlacePreferences.pdfCrop = PDFCrop.CROP_CONTENT_VISIBLE_LAYERS;");

    frame::image (gFrame, "$DESKTOP/abc.pdf", 1);

    sprintf (resetCmd, "app.pdfPlacePreferences.pdfCrop = %s;", oldCrop);
    run_javascript (resetCmd);

    return 0;
}





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



#include "internal/types.h"

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

    return 0;
}




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


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


treshold since v3.3 R3500, 8. Mar 2013


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


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





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







comet.CFrame.setImage

Loading image placeholder

Use image::setclip if only the clip path is to change.








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



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







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Valid frame. If the frame isn't a Graphic Frame, it will be converted automatically


0 : current script frame






path

String or char*
-

complete path or URL to the image






alignment

int
kMiddle

see image positions






boundingBox

float
kFitBigContentProp

Image size in points


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


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


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





  #include "internal/types.h"




Embed a local image file into a frame.



#include "internal/text.h"
#include "internal/types.h"

int main ()
{
    char		imgFile[255];
    int 		res;
    char		dp[2000];

    document::folder (dp);
    strcpy (imgFile, dp);
    strcat (imgFile, "/");
    strcat (imgFile, "clara.JPG");
    res = frame::embed_file (gFrame, imgFile, kPlaceTopLeft, 0.0);

    if (res == 0) 	wlog ("", "Embedding '%s' successfully finished\n", imgFile);
    else			wlog ("", "Embedding '%s' done with error %d\n", imgFile, res);

    return 0;
}





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



#include "internal/text.h"
#include "internal/types.h"

int main ()
{
    char		imgFile[255];
    int 		res;

    strcpy (imgFile, "http://www.hi13.de/Auto.JPG");
    res = frame::embed_file (gFrame, imgFile, kPlaceTopLeft, 0.0);

    if (res == 0) 	wlog ("", "Embedding '%s' successfully finished\n", imgFile);
    else			wlog ("", "Embedding '%s' done with error %d\n", imgFile, res);

    return 0;
}



Version 2.0 R 644, 22. März 2008





priint:comet InDesign® Plug-Ins, comet_pdf







embed_image








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



Embedding an image in a frame.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Valid frame reference. If the frame is not a graphics frame, it is converted to a graphics frame.


0 : Current frame of the script






img

Image
-

Image binary data, see Image






alignment

int
kMiddle

see image positions






boundingBox

float
kFitBigContentProp

Image size in points


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


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


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







Version 2.0 R 644, 22. März 2008






priint:comet InDesign® Plug-Ins, comet_pdf





embed_file
image








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



Place a PDF into a given frame.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Frame into which the PDF is to be placed


0 : current script frame






path

String oder char*
-

Full local or UNC path to the PDF file to be placed in the document.
The path may start with a defined $ALIAS.


[Since v4.2 R33270] URLs are also allowed here.






pageIndex

int
1

Which page of the PDF should be placed?


≤0 : Last page

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




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








alignment

int
kMiddle

Position of the image in the frame, see image positions






bounding

float
kFitBigContentProp

Specification of the size of the image in the frame. Specification in points.


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


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


<0.0 : Fit image proportionally into a square frame of the amount of this size.
If the image is smaller, it will be resized accordingly.






transparentBkg

int
0

Should the background be transparent?


0 : No

1 : Yes






layer1, ...

String oder char*
0

Arbitrarily long list of layer names. All specified layers of the PDF file will be made visible, all others invisible.
If the list is empty, the layer visibility settings of the PDF file will be used.
Attention: It is not sufficient to set the layer visibility in the PDF with the layer eyes only,
you have to use the layer options for that! 


The specifications are ignored by comet_pdf and if the PDF file is given by an URL. In these cases the layer visibilities of the PDF are used.






0, behavior

0, int
0, 2

Behavior with undefined page numbers. The specification is made, separated by a 0, after the layer names


1 : Cancel with pageNotFoundErr (1219)

2 : First page

3 : Last page





  #include "internal/types.h"






err_code = frame::place_pdf (gFrame, "$DESKTOP/a.pdf", 3);





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



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



Version 2.1, 23. Feb 2010 (R1760)

Parameter behavior since v4.2 R32235, 1. Feb 2023

ULR support since v4.2 R33270






priint:comet InDesign® Plug-Ins, comet_pdf







comet.CFrame.setImage








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



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







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Frame into which the PDF is to be placed


0 : current script frame






path

String oder char*
-

Full local or UNC path to the PDF file to be placed in the document.
The path may start with a defined $ALIAS.


[Since v4.2 R33270] URLs are also allowed here.






pageIndex

int
1

Which page of the PDF should be placed?


≤0 : Last page

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




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








alignment

int
kMiddle

Position of the image in the frame, see image positions






bounding

float
kFitBigContentProp

Specification of the size of the image in the frame. Specification in points.


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


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


<0.0 : Fit image proportionally into a square frame of the amount of this size.
If the image is smaller, it will be resized accordingly.






transparentBkg

int
0

Should the background be transparent?


0 : No

1 : Yes






cropTo

int
-1

Crop pdf to bounding box


-1 : Use InDesign import options

0 : Crop to content (visible layers)

1 : Use InDesign import options

2 : Crop to art

3 : Crop to page

4 : Crop to trim

5 : Crop to bleed

6 : Crop to media

7 : Crop to content (all layers), since CS5


The red marked wishes are not supported bycomet_pdf.






layer1, ...

String oder char*
0

Arbitrarily long list of layer names. All specified layers of the PDF file will be made visible, all others invisible.
If the list is empty, the layer visibility settings of the PDF file will be used.
Attention: It is not sufficient to set the layer visibility in the PDF with the layer eyes only,
you have to use the layer options for that! 


The specifications are ignored by comet_pdf and if the PDF file is given by an URL. In these cases the layer visibilities of the PDF are used.






0, behavior

0, int
0, 2

Behavior with undefined page numbers. The specification is made, separated by a 0, after the layer names


1 : Cancel with pageNotFoundErr (1219)

2 : First page

3 : Last page





  #include "internal/types.h"





err_code = frame::place_pdf_with_crop (gFrame, "$DESKTOP/a.pdf", 3);





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



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



seit Version v3.3 R3011, 25.05.2012

Parameter behavior since v4.2 R32235, 1. Feb 2023

ULR support since v4.2 R33270






priint:comet InDesign® Plug-Ins, comet_pdf







comet.CFrame.setImage








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



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







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
- 

Graphic Frame of the image to be moved






x

float
-

Relative image position to the left upper frame corner in points






y

float
-

Relative image position to the left upper frame corner in points









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



int main ()
{
    float    width, height;

    frame::image_getsize (gFrame, &width, &height);

    frame::image_pos (gFrame, 12.0, 34.0);
    frame::image_size (gFrame, 100.0, 140.0);
    frame::image_scale (gFrame, 0.5, 0.7777);
    frame::image_rotate (gFrame, -30.0, width/2.0, height/2.0);
    frame::image_skew (gFrame, -30.0, width/2.0, height/2.0, 90.0);

    return 0;
    
}



Version 1.1.6





priint:comet InDesign® Plug-Ins, comet_pdf









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



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







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
- 

Graphic Frame of the image to be resized






x

float
-

New image width in points






y

float
-

New image height in points






refPoint

int
kRefPointTopLeft Scaling reference point


kRefPointTopLeft

kRefPointTopCenter

kRefPointTopRight

kRefPointLeftCenter

kRefPointCenter

kRefPointRightCenter

kRefPointBottomLeft

kRefPointBottomCenter

kRefPointBottomRight


 





refX, refY

float, float
0.0, 0.0

Reference point in points relative to the top left corner of the given frame.





  #include "internal/types.h"




See example for image_getpos.




Version 1.1.6

refPoint, refX, refY since Version 2.1 R684, 23.4.2008






priint:comet InDesign® Plug-Ins, comet_pdf





comet.CFrame.setImageSize








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



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







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
- 

raphic Frame of the image to be scaled






x

float
-

New scale for the image width (1.0 for 100%)






y

float
-

New scale for the image height (1.0 for 100%)






refPoint

int
kRefPointTopLeft

scaling reference point


kRefPointTopLeft

kRefPointTopCenter

kRefPointTopRight

kRefPointLeftCenter

kRefPointCenter

kRefPointRightCenter

kRefPointBottomLeft

kRefPointBottomCenter

kRefPointBottomRight







refX, refY

float, float
0.0, 0.0

Reference point in points relative to the top left corner of the given image.






frameRelativeRefPoint

int
0

Use the graphicframe as base for the reference point (instead of the image)


0 : no

1 : yes





  #include "internal/types.h"




See example for image_getpos.






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



int main ()
{
    float			x, y, rot;
    float			w, h;

    frame::image_getsize (gFrame, &w, &h);
    frame::image_getscale (gFrame, &x, &y);
    frame::image_getrotation (gFrame, &rot);

    frame::image_scale (gFrame, x, -y, kRefPointCenter);
    frame::image_rotate (gFrame, rot+180.0, w/2.0, h/2.0);

    return 0;
}


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



Version 1.1.6

refPoint, refX, refY since Version 2.1 R684, 23.4.2008

frameRelativeRefPointnt since v3.3 R2750, 23.11.2011





priint:comet InDesign® Plug-Ins, comet_pdf





comet.CFrame.setImageScale








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



  Rotate the image inside a given Graphic Frame.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
- 

Graphic Frame of the image to be rotated






angle

float
-

Rotation angle in degrees






refpointX

float
0.0

X value of the reference point for the rotation in points relative to the left edge of the image, not the frame.






refpointY

float
0.0

Y-value of the reference point for the rotation in points relative to the upper edge of the image, not the frame.





  #include "internal/types.h"




See example for image_getpos.






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



int main ()
{
    float			x, y, rot;
    float			w, h;

    frame::image_getsize (gFrame, &w, &h);
    frame::image_getscale (gFrame, &x, &y);
    frame::image_getrotation (gFrame, &rot);

    frame::image_scale (gFrame, x, -y, kRefPointCenter);
    frame::image_rotate (gFrame, rot+180.0, w/2.0, h/2.0);

    return 0;
}


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



Version 1.1.6





priint:comet InDesign® Plug-Ins, comet_pdf





comet.CFrame.setImageRotation








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



 Skew the image inside a given Graphic Frame.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
- 

Graphic Frame of the image to be skewd






angle

float
-

Skew angle in degrees






refpointX

float
0.0

X value of the reference point for the skewing in points relative to the left edge of the image, not the frame.






refpointY

float
0.0

Y value of the reference point for the skewing in points relative to the upper edge of the image, not the frame.









See example for image_getpos.




Version 1.1.6





priint:comet InDesign® Plug-Ins, comet_pdf



comet.CFrame.setImageSkew








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



Rotate a frame.


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








Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
- 

Frame to rotate






angle

float
-

Rotation angle in degrees counter clock wise






refpointX

float
0.0

Ignored since v4.1 R21457






refpointY

float
0.0

Ignored since v4.1 R21457






suprRules

int
1

Suppres layout rules "After geometry changes" while executing the command?


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


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






refPoint

int
kRefPointCenter

\Fix point of roation


-1 : Ignore and use refpointX and refpointY


kRefPointTopLeft

kRefPointTopCenter

kRefPointTopRight

kRefPointLeftCenter

kRefPointCenter

kRefPointRightCenter

kRefPointBottomLeft

kRefPointBottomCenter

kRefPointBottomRight






  #include "internal/types.h"


Version 1.4 R336 (18. April 2007)

Parameter suprRules since v3.3 R3405, 5. Feb. 2012

Parameter refPoint siince v4.1 R21457, 11. Jan 2018





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







get_rotate

comet.CPageItem.setRotation








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



Get the current rotation of a frame.







Name
Type
Default
Description





Return

float
 

Rotation angle in degrees






frameRef

ItemRef
-

Valid frame reference


0 : current script frame






refpointX, refpointY

float*, float*
0, 0

Reference point for rotation


0 : ignore

Ignored by Illustrator










int main ()
{
    float		l, t, r, b;
    float		w, h;
    float		f;
    float		refx, refy;
    float		sx, sy;

    frame::bbox (gFrame, &l, &t, &r, &b);
    frame::size (gFrame, &w, &h);
    wlog ("", "Frame %d : %f x %f (%f x %f)\n",
     		item::getint (gFrame),
     		r-l, b-t,
     		w, h);

    f = frame::get_rotate (gFrame, &refx, &refy);
    wlog ("", "	rotation	: %f (%f, %f)\n", f, refx, refy);

    f = frame::get_skew (gFrame);
    wlog ("", "	skew	: %f\n", f);

    f = frame::get_scale (gFrame, &sx, &sy);
    wlog ("", "	scale	: %f x %f\n", sx, sy);

    return 0;
}



Version 3.2 R2255, 3. Feb. 2011





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







rotate

comet.CPageItem.getRotation








static   float get_skew(ItemRef frameRef)



Get the current skew angle of a frame.







Name
Type
Default
Description





Return

float
 

Skew angle in degrees






frameRef

ItemRef
-

Valid frame reference


0 : current script frame










int main ()
{
    float		l, t, r, b;
    float		w, h;
    float		f;
    float		refx, refy;
    float		sx, sy;

    frame::bbox (gFrame, &l, &t, &r, &b);
    frame::size (gFrame, &w, &h);
    wlog ("", "Frame %d : %f x %f (%f x %f)\n",
     		item::getint (gFrame),
     		r-l, b-t,
     		w, h);

    f = frame::get_rotate (gFrame, &refx, &refy);
    wlog ("", "	rotation	: %f (%f, %f)\n", f, refx, refy);

    f = frame::get_skew (gFrame);
    wlog ("", "	skew	: %f\n", f);

    f = frame::get_scale (gFrame, &sx, &sy);
    wlog ("", "	scale	: %f x %f\n", sx, sy);

    return 0;
}



Version 3.2 R2255, 3. Feb. 2011





priint:comet InDesign® Plug-Ins, comet_pdf







skew
comet.CPageItem.getSkew








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



Get the current frame scaling.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Valid frame reference


0 : current script frame






scalex, scaley

float*, float*
0, 0

Current scalings (1.0 means 100%)


0 : ignore










int main ()
{
    float		l, t, r, b;
    float		w, h;
    float		f;
    float		refx, refy;
    float		sx, sy;

    frame::bbox (gFrame, &l, &t, &r, &b);
    frame::size (gFrame, &w, &h);
    wlog ("", "Frame %d : %f x %f (%f x %f)\n",
     		item::getint (gFrame),
     		r-l, b-t,
     		w, h);

    f = frame::get_rotate (gFrame, &refx, &refy);
    wlog ("", "	rotation	: %f (%f, %f)\n", f, refx, refy);

    f = frame::get_skew (gFrame);
    wlog ("", "	skew	: %f\n", f);

    f = frame::get_scale (gFrame, &sx, &sy);
    wlog ("", "	scale	: %f x %f\n", sx, sy);

    return 0;
}



Version 3.2 R2255, 3. Feb. 2011





priint:comet InDesign® Plug-Ins, comet_pdf







resize
comet.CPageItem.getScale








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



Scale a frame by the given scaling factors.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
- 

Valid document frame






xscale

float
-

Factor for changing the frame width






yscale

float
-

Factor for changing the frame height






refpointX

float
0.0

X value of the fix point in points relative to the left edge of the frame


The value is ignored by comet_pdf and the refPoint is used always.






refpointY

float
0.0

Y value of the fix point in points relative to the upper edge of the frame


The value is ignored by comet_pdf and the refPoint is used always.






suprRules

int
1

Suppres layout rules "After geometry changes" while executing the command?


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


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






refPoint

int 
-1

Reference point for scaling


-1 : Ignore and use refpointX and refpointY verwenden


kRefPointTopLeft (0)

kRefPointTopCenter(1)

kRefPointTopRight(2)

kRefPointLeftCenter(3)

kRefPointCenter(4)

kRefPointRightCenter(5)

kRefPointBottomLeft(6)

kRefPointBottomCenter(7)

kRefPointBottomRight(8)





  #include "internal/types.h"



Version 1.4 R336 (18. April 2007)

Parameter suprRules since v3.3 R3405, 5. Feb. 2012





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







get_scale
get_skew
comet.CPageItem.setScale

prefs::get_transform_settings
prefs::set_transform_settings







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



Scale a frame to the given factors.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
- 

Valid document frame






xscale

float
-

New frame width in percent, 1.0 corresponds to 100%.






yscale

float
-

New frame height in percent, 1.0 corresponds to 100%.






refpointX

float
0.0

X value of the fix point in points relative to the left edge of the frame


The value is ignored by comet_pdf and the refPoint is used always.






refpointY

float
0.0

Y value of the fix point in points relative to the upper edge of the frame


The value is ignored by comet_pdf and the refPoint is used always.






suprRules

int
1

Suppres layout rules "After geometry changes" while executing the command?


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


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






refPoint

int 
-1

Reference point for scaling


-1 : Ignore and use refpointX and refpointY verwenden


kRefPointTopLeft (0)

kRefPointTopCenter(1)

kRefPointTopRight(2)

kRefPointLeftCenter(3)

kRefPointCenter(4)

kRefPointRightCenter(5)

kRefPointBottomLeft(6)

kRefPointBottomCenter(7)

kRefPointBottomRight(8)





  #include "internal/types.h"



v4.1.6 R26411, 12. Dec. 2019





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







get_scale
get_skew

prefs::get_transform_settings
prefs::set_transform_settings







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



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







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
- 

Valid document frame






angle

float
-

Skew angle






refpointX

float
0.0

X value of the fix point for the skewing in points relative to the left edge of the frame


Ingored from comet_pdf, the reference point here is the the top left corner always.






refpointY

float
0.0

Y value of the fix point for the skewing in points relative to the upper edge of the frame


Ingored from comet_pdf, the reference point here is the the top left corner always.






rotation

float
0.0

Value of the optional rotation in addition to the skew,  not supported by InDesign® CS3.






suprRules

int
1

Suppres layout rules "After geometry changes" while executing the command?


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


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







Version 1.4 R336 (18. April 2007)

Parameter suprRules since v3.3 R3405, 5. Feb. 2012





priint:comet InDesign® Plug-Ins, comet_pdf







get_skew
comet.CPageItem.setSkew







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



see frame::image







Name
Type
Default
Description





Return

int
 

0 oder Fehlercode







Version 1.1.7, Januar 2005





priint:comet InDesign® Plug-Ins



frame::image








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



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




Using comet_pdf the function is a NOP only.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Frame, the connection of which is to be updated






uiFlags

int
0

Import dialog which is to be displayed

0 suppress all dialogs

1 Display the next dialog
2 Display all dialogs






doAll

int
0

InDesign® does allow itself one small slip up : If the target file
of a link is renamed and another file is given the name, which is to be specified in the link,
InDesign® sometimes does not recognise this change. By giving 1 for the parameter, you compell
that the reference is newly loaded in all cases. the Reimport of all
references can take some time to complete.







Version 1.1.7, Januar 2005





priint:comet InDesign® Plug-Ins, comet_pdf









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



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




Using comet_pdf the function is a NOP only.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






uiFlags

int
0

Import dialog which is to be displayed

0 suppress all dialogs

1 Display the next dialog
2 Display all dialogs






doAll

int
0

InDesign® does allow itself one small slip up : If the target file
of a link is renamed and another file is given the name, which is to be specified in the link,
InDesign® sometimes does not recognise this change. By giving 1 for the parameter, you compell
that the reference is newly loaded in all cases. the Reimport of all
references can take some time to complete.






includePasteboard

int
0

Also reimport frames on paste board?


0 : No. Do only reimport page frames

otherwise : yes







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





priint:comet InDesign® Plug-Ins, comet_pdf









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



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




Using comet_pdf the function is a NOP only.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






uiFlags

int
0

Import dialog which is to be displayed

0 suppress all dialogs

1 Display the next dialog
2 Display all dialogs






doAll

int
0

InDesign® does allow itself one small slip up : If the target file
of a link is renamed and another file is given the name, which is to be specified in the link,
InDesign® sometimes does not recognise this change. By giving 1 for the parameter, you compell
that the reference is newly loaded in all cases. the Reimport of all
references can take some time to complete.







Version 1.1.7, Januar 2005





priint:comet InDesign® Plug-Ins, comet_pdf









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



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




Using comet_pdf the function is a NOP only.








Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameList

ItemList
-

List of the frames which are to be updated.






uiFlags

int
0

Import dialog which is to be displayed

0 suppress all dialogs

1 Display the next dialog
2 Display all dialogs






doAll

int
0

InDesign® does allow itself one small slip up : If the target file
of a link is renamed and another file is given the name, which is to be specified in the link,
InDesign® sometimes does not recognise this change. By giving 1 for the parameter, you compell
that the reference is newly loaded in all cases. the Reimport of all
references can take some time to complete.







Version 1.1.7, Januar 2005





priint:comet InDesign® Plug-Ins, comet_pdf









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



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







Name
Type
Default
Description





Return

String or char* (Depends on parameter name)
 

Name of the layer on which the specified frame lies, or empty string. Same as parameter name






itemRef

ItemRef
-

Frame the layer of which is to be ascertained.






name

String or char*
-

Reserved memory for the result







Version 1.1.7, Januar 2005





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





comet.CPageItem.getLayer







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



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




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




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







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frame

ItemRef
-

Inline frame or image (but not the frame containing the image)






parent

ItemRef
-

Reserved memory for the result. The reference is only fulfilled, if
the function returns the error code 0






textPos

int*
0

Text position of the frame. The value is set only for inline frames, otherwise it is -1.







Version 1.1.7, Januar 2005

Parameter textPos seit v4.1.8 R29412, 19. Nov 2021





priint:comet InDesign® Plug-Ins, comet_pdf



frame::isinline
frame::textframe

comet.CPageItem.getParent








static   int isinline(ItemRef frame)



 Is the specified frame located within the text?







Name
Type
Default
Description





Return

int
 

1 : ja

0 : nein






frame

ItemRef
-

Frames the inline characteristics of which are to be inquired.







Version 1.1.7, Januar 2005





priint:comet InDesign® Plug-Ins, comet_pdf



frame::isinline
frame::textframe
position_visible








static   int textframe(ItemRef frame, ItemRef textFrame)



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




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







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frame

ItemRef
-

Frames the text frames of which are to be inquired. If the specification is 0, the text frame
of the current text model or the value of the variable gFrame is inquired.






textFrame

ItemRef
-

Reserved memory for the result. The reference is only fulfilled, if
the function returns the error code 0.







Please use the frame::parent function instead.


Version 1.1.7, Januar 2005





priint:comet InDesign® Plug-Ins, comet_pdf





frame::isinline
frame::parent








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



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







Name
Type
Default
Description





Return

int
 

-1199







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








static   int hasfloating(ItemRef textframe, int pos)



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







Name
Type
Default
Description





Return

int
 

0







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








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



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







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frames

ItemList
-

Liste valid frame references






newFrame

itemRef
-

allocated memory for the result. If the frames are successfully grouped
the variable will contain a valid reference to the group frames.





  #include "internal/text.h"




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



#include "internal/text.h"

int main ()
{
    DataPool	pool		= datapool::alloc ();
    ItemList	frames		= itemlist::alloc ();
    ItemRef		groupRef	= item::alloc ();
    ItemList	items		= 0;
    float		l			= 0.0;
    float		t			= 0.0;
    float		r, b;
    int			i;
    int			textpos;

    if (!textmodel::available ()) return 0;

    // Insert own frames into document
    // The templates 2-4 must be set up.
    for (i = 2; i<5; i++)
    {
        // Insert template
        // items are thereby aiutomatically allocated
        items = document::place_items (pool, "data", "pageitems", i, l, t);

        // Group inserted frames
        itemlist::appendlist (frames, items);

        // Next template position
        // The list items are then deleted. 
        itemlist::bbox (items, &l, &t, &r, &b);
        itemlist::release (items);
        items = 0;
        t = b + 2.0;
    }

    // Group inserted templates
    frame::group (frames, groupRef);

    // Let group float
    textmodel::floating (groupRef, textmodel::start (),
     	kRightHanded, 5.0,
     	kBelowTop, 0.0);

    return 0;
}



Version 1.2.1 (25. August 2005)





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







ItemList
itemlist::append
...
ungroup

comet.frame.createGroup








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



 Resolve frame grouping.





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


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




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



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




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

ItemRef		newRef		= item::alloc ();
ItemRef		oldGroup	= item::alloc ();
ItemRef		newGroup	= item::alloc ();
ItemList 	li			= itemlist::alloc();

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

 	frame::regrouped (oldGroup, newGroup);
}



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





ItemRef		oldGroup	= item::alloc ();
ItemList 	li			= itemlist::alloc();
int			i;

if (frame::get_group(gFrame, oldGroup) == 0)
{
 	frame::ungroup(oldGroup, li);

 	for (i = 0; i < itemlist::length (li); i++)
 	{
 		placeholder::load (fr, 0, -2, 0, 1);
 		placeholder::build (fr);
 	}
}










Name
Type
Default
Description





Return

int
 

0 or ErrorCode






groupFrame

ItemRef
-

Frame grouping to be resolved






groupedItems

ItemList
0

List of frames grouped by the frame

0 : not needed

otherwise : with itemlist::alloc allocated result list





  #include "internal/types.h"




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




 ⇒ 



#include "internal/types.h"

int main ()
{
    ItemRef		groupRef	= item::alloc ();
    ItemRef		newframe	= item::alloc ();
    ItemList	grouped		= itemlist::alloc ();
    float		l, t, r, b;
    char		lay[256];

    if (gRun > 1) return 0;

    if (frame::get_group (gFrame, groupRef))
    {
        showmessage ("Rahmen nicht gruppiert.");
        return 0;
    }
    frame::ungroup (groupRef, grouped);

    itemlist::bbox (grouped, &l, &t, &r, &b);
    frame::create2 (
     	newframe,
     	kStar,
     	r+10.0, t, r+130.0, t+120.0,
     	page::get (gFrame),
     	frame::get_layer (gFrame, lay),
     	0,		// Spaltenanzahl
     	0,		// vertikale Spalten
     	0.0,	// Spaltenabstand
     	5, 40);
    frame::color_rgb (newframe, 255, 0, 0, 0);
    frame::stroke_rgb (newframe, 0, 0, 0, 5.0);
    itemlist::append (grouped, newframe);

    frame::group (grouped);

    return 0;
}



Version 1.2.1 (25. August 2005)


Parameter groupedItems since Version 1.3.4 (P/R 74)





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







group
add_to_group
regrouped

comet.CGroup.resolve








static   int group_content(ItemRef groupFrame, ItemList groupedItems)




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







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






groupFrame

ItemRef
-

group frame, see get_group






groupedItems

ItemList
0

List of content, must be allocated using itemlist::alloc









Select all frames beloning to the same group as gFrame



#include "internal/types.h"

int main ()
{
    ItemRef			groupRef	= item::alloc ();
    ItemList		grouped		= itemlist::alloc ();
    ItemRef			nth			= item::alloc ();
    int				i;

    if (gRun > 1) return 0;

    if (frame::get_group (gFrame, groupRef))
    {
        showmessage ("Your frame is not part of an InDesign Group.");
        return 0;
    }
    frame::group_content (groupRef, grouped);

    for (i = 0; i < itemlist::length (grouped); i++)
    {
        frame::select (itemlist::get (grouped, nth, i), false, false);
    }

    return 0;
}


Version 1.3.4 (P/R 74)





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







comet.CGroup.getMembers








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




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







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

valid frame






groupRef

ItemRef
0

On successful return : Reference to the InDesign group


0 : Ignore

Otherwise : With item::alloc allocated result variable









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



int get_top (ItemRef fr, ItemRef top)
{
    ItemRef		parent	= item::alloc ();
    ItemRef		child	= item::alloc ();

    item::assign (top, fr);
    item::assign (child, fr);

    while (frame::get_group (child, parent) == 0)
    {
        item::assign (child, parent);
        item::assign (top, parent);
    }

    item::release (parent);
    item::release (child);

    return frame::is_valid (top);
}

int main ()
{
    ItemRef		top		= item::alloc ();

    if (!get_top (gFrame, top))	return 0;

    frame::moveto (top, 36.0, 36.0);

    return 0;
}


Version 1.3.4 (P/R 74)





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







comet.CPageItem.getGroup








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



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







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






oldGroup

ItemRef
-

Resolved group






newGroup

ItemRef
0

New group. May be 0 (See here to learn more in this case!







Version 3.2 R2267, 7.Feb.2011





priint:comet InDesign® Plug-Ins, comet_pdf







add_to_group
add_list_to_group
ungroup
group







static   int add_to_group(ItemRef frameRef, ItemRef sibling)



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







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Valid frame or group reference






sibling

ItemRef
-

Add this frame to the group.









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



int main ()
{
    ItemRef		f	= item::alloc ();
    int			r;
    int			l	= 36;
    int			t	= 36;
    int			i;

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

    return 0;
}


Version 3.2 R2267, 7.Feb.2011





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







is_group
regrouped
ungroup
group
group_content
add_list_to_group

comet.CGroup.addMembers








static   int add_list_to_group(ItemRef frameRef, ItemList siblings)



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







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Valid frame or group reference






siblings

ItemList
-

Add this frames to the group.









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



int main ()
{
    ItemRef		f	= item::alloc ();
    ItemList	fl	= itemlist::alloc ();
    int			r;
    int			l	= 36;
    int			t	= 36;
    int			i;

    for (i = 0; i < 4; i++)
    {
        frame::create_textframe (f,
         	l+(i*100),
         	t,
         	l+90+(i*100),
         	t+200,
         	page::get (gFrame),
         	"");
        frame::color_rgb (f, 56+(i*50), 128, 0);
        itemlist::append (fl, f);
    }

    frame::add_list_to_group (gFrame, fl);

    return 0;
}


Version 3.2 R2267, 7.Feb.2011





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







is_group
regrouped
ungroup
group
group_content

comet.CGroup.addMembers








static   int inlinepos(ItemRef inlineframe)



 Ascertain the text position of an inliner frame.







Name
Type
Default
Description





Return

int
 

Textposition oder -1






inlineframe

ItemRef
-

Inlinerahmen









Get all inlines of the currently selected table cell.



ItemList inlines_of_cell (ItemRef frame, Table T, int row, int col)
{
    ItemList	inlines		= itemlist::inlines (frame);
    ItemList	cellframes	= itemlist::alloc ();
    ItemRef		f			= item::alloc ();
    int			start, len, pos, i;

    table::cell::get_textpos (T, col, row, &start, &len);

    for (i = 0; i < itemlist::length (inlines); i++)
    {
        itemlist::get (inlines, f, i);
        pos = frame::inlinepos (f);
        if (pos >= start)
        {
            itemlist::append (cellframes, f);
        }
    }

    itemlist::release (inlines);
    return cellframes;
}

int main ()
{
    int 		start, end, row, col;
    Table		T 		= table::alloc ();
    ItemRef		frame	= item::alloc ();
    ItemList	inlines;

    textmodel::selection (&start, &end, frame, 0, T, &col, &row);
    if (table::is_valid (T))
    {
        inlines	= inlines_of_cell (frame, T, row, col);

        wlog ("", "# %d inlines in cell [r%d, c%d]\n", itemlist::length (inlines), row, col);

        itemlist::release (inlines);
    }

    return 0;
}


Version 1.1.7, Januar 2005





priint:comet InDesign® Plug-Ins, comet_pdf







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








static   int set_creationdate(ItemRef f)



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







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






f

ItemRef
-

Valid frame reference







Version 1.2.1 (30. August 2005)





priint:comet InDesign® Plug-Ins, comet_pdf









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



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







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






f

ItemRef
-

Valid frame reference

0 - Use current script frame






mode

int
-

Contour type


-1 kWrapUndef - Leave contour type unchanged

0 kWrapNone -  no effect on text

1 kWrapBand -  text leads past area of strip

2 kWrapNextFrame -  text continues in next frame

3 kWrapBothSides -  text on both sides of object

4 kWrapWithinHoles -  text within holes in object

6 kWrapManualContour -  text follows the standoff shape	(implies kWrapBothSides)

7 kWrapLeftContour -  text wraps only to the left side of the standoff

8 kWrapRightContour -  text wraps only to the right side of the standoff






left

float
-1000.0

Left contour width

-1000.0 - Ignore


In case of using a contour, the value is set but not used anyway.






top

float
-1000.0

Upper contour height

-1000.0 - Ignore


In case of using a contour, the value is used as the distance around the shape.






right

float
-1000.0

Right contour width

-1000.0 - Ignore


In case of using a contour, the value is set but not used anyway.






bottom

float
-1000.0

Lower contour height

-1000.0 - Ignore


In case of using a contour, the value is set but not used anyway.





  #include "internal/types.h"


Version 1.2.2 (18 October 2005)





priint:comet InDesign® Plug-Ins, comet_pdf





comet.CFrame.setWrap








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



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







Name
Type
Default
Description





Return

int
 

Kontortyp


-1 kWrapUndef - Contour type could not be ascertained

0 kWrapNone -  no effect on text

1 kWrapBand -  text leads past area of strip

2 kWrapNextFrame -  text continues in next frame

3 kWrapBothSides -  text on both sides of object

4 kWrapWithinHoles -  text within holes in object

6 kWrapManualContour -  text follows the standoff shape	(implies kWrapBothSides)

7 kWrapLeftContour -  text wraps only to the left side of the standoff

8 kWrapRightContour -  text wraps only to the right side of the standoff






f

ItemRef
-

Valid frame reference

0 - use current script frame






left

float*
0

Left contour width, may be 0 (ignore return value).






top

float*
0

Upper contour height, may be 0 (ignore return value).






right

float*
0

Right contour width, may be 0 (ignore return value).






bottom

float*
0

Lower contour height, may be 0 (ignore return value).





  #include "internal/types.h"


Version 1.2.2 (18 October 2005)





priint:comet InDesign® Plug-Ins, comet_pdf





comet.CFrame.getWrap








static   int wrap_ignore(ItemRef f, int state)



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







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






f

ItemRef
-

Valid frame reference

0 - Use current script frame






state

int
-

0 - turn wrapping off

otherwise - activate wrapping







Version 1.2.2 (18 October 2005)





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



comet.CFrame.setWrapIgnore








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



comet.CFrame.getWrapIgnore








static   int wrap_invert(ItemRef f, int state)



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







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






f

ItemRef
-

Valid frame reference

0 - Use current script frame






state

int
-

0 -Use wrap normally

otherwise - use inner part of the frame as wrap


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







Version 1.2.2 (18 October 2005)





priint:comet InDesign® Plug-Ins, comet_pdf









static   int getwrap_invert(ItemRef f)



 Is the frame wrap inverted?







Name
Type
Default
Description





Return

int
 

1 - Wrap inverted or status could not be ascertained

0 - Wrap used as "normal"






f

ItemRef
-

Valid frame reference

0 - Use current script frame







Version 1.2.2 (18 October 2005)





priint:comet InDesign® Plug-Ins









static   int wrap_zorderbased(ItemRef f, int state)



Take care on Z order of text wrap.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






f

ItemRef
-

Valid frame reference

0 - Use current script frame






state

int
-

0 -Use wrap normally

otherwise - Use contour only if the frame lies above the text







Version 4.0.5 R9830, 14. Jan 2016





priint:comet InDesign® Plug-Ins, comet_pdf











static   int getwrap_zorderbased(ItemRef f)



Check Z order of frame for text wrapings?







Name
Type
Default
Description





Return

int
 

0 : Z order is ignored or ErrorCode

1 : Yes. Text wrap is only applied for frames behind the contour.






f

ItemRef
-

Valid frame reference

0 - Use current script frame







Version 4.0.5 R9830, 14. Jan 2016





priint:comet InDesign® Plug-Ins, comet_pdf











static   int wrap_side(ItemRef f, int side)



Set options for text wraps around frames and objects.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






f

ItemRef
-

Valid frame reference

0 - Use current script frame






side

int
-

0 - Right and eft side

1 - Left side

2 - Right side

3 - To binding

4 - Away binding

5 - Largest line (not for comet_pdf)







Version 4.0.5 R9830, 14. Jan 2016





priint:comet InDesign® Plug-Ins, comet_pdf











static   int getwrap_side(ItemRef f)



Get options for text wraps around frames and objects.







Name
Type
Default
Description





Return

int
 

-1 : Error
0 : Right and eft side

1 : Left side

2 : Right side

3 : To binding

4 : Away binding

5 : Largest line (not for comet_pdf)






f

ItemRef
-

Valid frame reference

0 - Use current script frame







Version 4.0.5 R9830, 14. Jan 2016





priint:comet InDesign® Plug-Ins, comet_pdf











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



Set options for text wraps around images. Don't forget to call frame::wrap before setting the contour options of the image!







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






f

ItemRef
-

Valid frame reference

0 - Use current script frame






type

int
0

0 : Bounding Box (not in comet_pdf)

1 : Edge detection (not in comet_pdf)

2 : Alpha channel

3 : Photoshop path

4 : Graphic Frame (not in comet_pdf)

5 : Same as clipping






pathindex

int
0

0-based index of Photoshop path. comet_pdf ignores this value, please use pathname instead.






pathname

String or char*
0

Name of Photoshop path. If this value is not empty, pathindex is ignored.






alphindex

int
0

0-based index of alpha channle. comet_pdf ignores this value, please use alphaname instead.






alphname

String or char*
0

Name of alpha channle. If this value is not empty, alphaindex is ignored.






tolerance

float
5.0

0.0 - 100.0


Tolerance for edge detection (not in comet_pdf).


Edge detection based on the image or an alpha channel occurs in two steps.
The first step generates a polygonal path which perfectly matches what InDesign®
believes is the edge.  Because the polygonal path may contain thousands of points,
it is smoothed into a bezier path during the second step if tolerance is non-zero.
During this smoothing step, the tolerance indicates how closely the resulting path
must match A value between 0 and 100 which indicates how closely the resulting path must
match the polygonal path from step 1.






treshhold

int
255

0 - 255


Treshhold for edge detection (not in comet_pdf).


During edge detection of an image or alpha channel, the source pixels are converted
to grayscale and then to a 1-bit bitmap.  The threshhold is a value between 0 and 255.  Any gray value
greater than or equal to the threshold will be mapped to white.  All other pixels will be mapped to black.






allowholes

int
0

Allow holes in case of edge detections? (not in comet_pdf)







Version 4.0.5 R9830, 14. Jan 2016





priint:comet InDesign® Plug-Ins, comet_pdf











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



Get options for text wraps around frames and objects.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






f

ItemRef
-

Valid frame reference

0 - Use current script frame






type

int
0

Pointer to variable for result (0 allowed):

1 : Edge detection (not in comet_pdf)

2 : Alpha channel

3 : Photoshop path

4 : Graphic Frame (not in comet_pdf)

5 : Same as clipping






pathindex

int
0

Result variable for 0-based Photoshop path index, can be 0.






pathname

String or char*
0

Result variable for Photoshop path name, can be 0.






alphaindex

int
0

Result variable for 0-based alpha channel index, can be 0.






alphaname

String or char*
0

Result variable for alpha channel name, can be 0.






tolerance

float*
0

Result variable for tolerance in case of edge detection, can be 0.






treshhold

int*
0

Result variable for treshhold in case of edge detection, can be 0.






allowholes

int*
0

Result variable for 'allow holes' in case of edge detection, can be 0.







Version 4.0.5 R9830, 14. Jan 2016





priint:comet InDesign® Plug-Ins, comet_pdf











static   char* gettext(
 	ItemRef f,
 	String str,
 	int pos = 0,
 	int len = -1,
 	int fmt = 0,
 	int showProgress = 0,
 	int tmRelative = 0)



 Get text content of a Text frame. The command functions analagously to the command textmodel::gettext
with an additional parameter which gives the required frame.



The export can be carried out as pure text (kExportPlain) or as text with formatting. Formattings
are written as InDesign® TaggedText. The format of the TaggedText is independent from
the settings of the export dialog and is always done with the following settings :

The function requires the following Includes


#include "internal/types.h"

#include "internal/text.h"



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








Name
Type
Default
Description





Return

char*
 

Contents. The returned pointer can be used in functions, which
expect char*-String as parameter.

The return value is read only, do NOT CHANGE.
The result will be overridden on following calls to the function.
See here to learn more about functions returning r/o char* values.







f

ItemRef
-

Valid frame reference

0 - Use current script frame






str

String
-

Allocated string object






position

int
0

Start position

>= 0	Text position

kSelection Current cursor position






len

int
kEnd

Number of characters that are to be retrieved






fmt

int
kExportPlain

Export format, see here






showProgress

int
false

Is a progress bar to be displayed for the export?

Ignored by Illustrator.






tmRelative

int
0

Position and length are relative to the current placeholder or to the current text model?


0 : placeholder

1 : text model

Ignored by Illustrator.





  #include "internal/text.h"

  #include "internal/types.h"





Here is a very simple example:



#include "internal/types.h"
#include "internal/text.h"

int main ()
{
    String 		str	= string::alloc ();

    frame::gettext (gFrame, str);
    showmessage ("--%s--", str);

    return 0;
}


Parameter tmRelative since version 2.1 R668, 16. April 2008

~Plus~-formats since v3.3 R2883, 20.04.2012





priint:comet InDesign® Plug-Ins, comet_pdf  (text format kExportPlain only), Illustrator (text format kExportPlain only)







comet.CFrame.getText








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



Determine the (geometric) type of a frame. The function determines whether a frame is a line, rectangle, square, etc.







Name
Type
Default
Description





Return

int
 

Frame Type


-1 kUndef : Unknown

0 kRectangle

1 kOval

2 kPolygon : Any polygon (including stars)

4 kSpline

5 kLine

6 kSquare

7 kCircle






f

ItemRef
0

Valid frame reference


0 :  Use current script frame






totalPoints

int*
0

How many shape points does the frame have?
If a frame consists of several paths, the corner points of the individual paths are added together.


0 : Ignore result





  #include "internal/types.h"




Find an example at get_color.




Version 1.3.4 (P/R 94)

kSquare and kCircle since v4.3 R34444





priint:comet InDesign® Plug-Ins







create
create2








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



Get the tranparency of a frame. Values are given in a range of 0.0 - 100.0.







Name
Type
Default
Description





Return

float
 

transparency in percents (0.0 - 100.0)

-1.0 : error






f

ItemRef
0

Valid frame

0 - use current script frame






opacType

int
0

What type of transparency?


0 : object

1 : contour

2 : fill

3 : content









Find an example at get_color.



Version 1.3.4 (P/R 94)

Parameter opacType since v3.3.1 R3956, 27. Jun 2013





priint:comet InDesign® Plug-Ins, comet_pdf







opacity








static   int get_blendmode(ItemRef f = 0)



Get frames blend mode.







Name
Type
Default
Description





Return

int
 

blend mode

-1 : error

otherwise : one of hte  blendmode-values at opacity






f

ItemRef
0

valid frame

0 - use current script frame









Find an example at get_color.



Version 1.3.4 (P/R 94)





priint:comet InDesign® Plug-Ins







opacity








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



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







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






f

ItemRef
0

valid frame

0 : current script frame






colName

String or char*
0

Name of color

0 : ignore

otherwise : allocated string






colSpace

int*
0

color space

0 : ignore

otherwise :

  kRGB
  kCMYK
  kLab






c1, c2, c3, c4

float*
0

color values

0 : ignore

otherwise : 

  r, g, b on kRGB

  c, m, y, k on kCMYK

  l, a, b on kLab







tint

float*
0

tint of color

0 : ignore

otherwise : 0.0 - 100.0





  #include "internal/types.h"




The example queries out some frame properties.



#include "internal/types.h"

int main ()
{
    char		colName[256];
    int			colSpace;
    float		c1, c2, c3, c4, tint;

    showmessage ("type : %d\nopacity : %f\nblendmode : %d",
     			frame::get_type (),
     			frame::get_opacity (),
     			frame::get_blendmode ());

    if (frame::get_color (0,colName,&colSpace,&c1,&c2,&c3,&c4,&tint) == 0)
    {
        if (colSpace == kRGB)
        {
            showmessage (
             		"color name : %s\nR : %f\nG : %f\nB : %f\nTint : %f\n",
             		colName,
             		c1, c2, c3, tint);
        }
        else if (colSpace == kCMYK)
        {
            showmessage (
             		"color name : %s\nC : %f\nM : %f\nY : %f\nK : %f\nTint : %f\n",
             		colName,
             		c1, c2, c3, c4, tint);
        }
        else if (colSpace == kLab)
        {
            showmessage (
             		"color name : %s\nL : %f\na : %f\nb : %f\nTint : %f\n",
             		colName,
             		c1, c2, c3, tint);
        }
        else
        {
            showmessage ("unknown color space");
        }
    }
    else showmessage ("Cannot detect color");

    return 0;
}



Version 1.3.4 (P/R 94)





priint:comet InDesign® Plug-Ins, comet_pdf







color
color_rgb

comet.CPageItem.getFillColor








static   int is_inline(ItemRef frame)



Is the frame an inline?







Name
Type
Default
Description





Return

int
 

1 : yes

0 : no






frame

ItemRef
-

valid frame







Version 1.3.4, R172





priint:comet InDesign® Plug-Ins, comet_pdf







frame::is_graphicframe
is_textframe
is_guide
is_standoff
position_visible

comet.CFrame.isInline








static   int is_directinline(ItemRef frame)



Is the frame a  direct inline?







Name
Type
Default
Description





Return

int
 

1 : yes

0 : no






frame

ItemRef
-

valid frame







Version 1.3.4, R172





priint:comet InDesign® Plug-Ins, comet_pdf







frame::is_graphicframe
is_textframe
is_guide
is_standoff








static   int is_textonpath(ItemRef frame)



Is the frame a  "text on path"?







Name
Type
Default
Description





Return

int
 

1 : yes

0 : no






frame

ItemRef
-

valid frame







Version 1.3.4, R172





priint:comet InDesign® Plug-Ins





frame::is_graphicframe
is_textframe
is_guide
is_standoff
set_top_options

comet.CPageItem.getType








static   int is_graphicframe(ItemRef frame)



Is the given frame a Graphic Frame?







Name
Type
Default
Description





Return

int
 

1 : yes

0 : no






frame

ItemRef
-

valid frame










int main ()
{
    int 		a	= frame::is_graphicframe (gFrame);
    int 		b	= frame::is_empty_graphicframe (gFrame);
    int 		c	= frame::has_embedded_image (gFrame);

    showmessage ("Graphic Frame : %d\nEmpty : %d\nEmbedded : %d\n", a, b, c);
    return 0;
}


Version 1.3.4, R172





priint:comet InDesign® Plug-Ins, comet_pdf







frame::is_graphicframe
is_textframe
is_guide
is_standoff
is_empty_graphicframe
has_embedded_image
placeholder::path

comet.CPageItem.getType








static   int is_empty_graphicframe(ItemRef frame)



I the given frame an empty Graphic Frame?







Name
Type
Default
Description





Return

int
 

1 : yes

0 : no






frame

ItemRef
-

valid frame










int main ()
{
    int 		a	= frame::is_graphicframe (gFrame);
    int 		b	= frame::is_empty_graphicframe (gFrame);
    int 		c	= frame::has_embedded_image (gFrame);

    showmessage ("Graphic Frame : %d\nEmpty : %d\nEmbedded : %d\n", a, b, c);
    return 0;
}


Version 2.1 R1830, 9. April 2010





priint:comet InDesign® Plug-Ins, comet_pdf







is_graphicframe
is_graphicframe
is_textframe
is_guide
is_standoff
has_embedded_image
placeholder::path








static   int has_embedded_image(ItemRef frame)



Does the given frame contain an embedded image?







Name
Type
Default
Description





Return

int
 

1 : yes

0 : no






frame

ItemRef
-

valid frame










int main ()
{
    int 		a	= frame::is_graphicframe (gFrame);
    int 		b	= frame::is_empty_graphicframe (gFrame);
    int 		c	= frame::has_embedded_image (gFrame);

    showmessage ("Graphic Frame : %d\nEmpty : %d\nEmbedded : %d\n", a, b, c);
    return 0;
}


Version 2.1 R1830, 9. April 2010





priint:comet InDesign® Plug-Ins, comet_pdf







is_graphicframe
is_graphicframe
is_textframe
is_guide
is_standoff
is_empty_graphicframe
placeholder::path
has_image
image_getpath








static   int has_image(ItemRef frame)



Does the given frame contain an image?







Name
Type
Default
Description





Return

int
 

1 : yes

0 : no






frame

ItemRef
-

valid frame







Version 3.1 R2022, 27.07.2010





priint:comet InDesign® Plug-Ins, comet_pdf





is_graphicframe
is_graphicframe
is_textframe
is_guide
is_standoff
is_empty_graphicframe
placeholder::path
has_embedded_image
image_getpath








static   int is_graphic(ItemRef frame)



Is the frame a  graphic?







Name
Type
Default
Description





Return

int
 

1 : yes

0 : no






frame

ItemRef
-

valid frame







Version 1.3.4, R172





priint:comet InDesign® Plug-Ins, Illustrator







frame::is_graphicframe
is_textframe
is_guide
is_standoff

comet.CPageItem.getType







static   int is_textframe(
 	ItemRef frame,
 	int*  startPos = 0,
 	int*  length = 0,
 	int*  idx = 0,
 	ItemRef firstFrame = 0)



Is the frame a textframe?







Name
Type
Default
Description





Return

int
 

1 : Yes

0 : No






frame

ItemRef
-

valid frame






startPos

int*
0

On successful return it contains the first text position in the frame






length

int*
0

On successful return it contains the length of the text shown in the frame






idx

int*
0

On successful return it contains the (0-based) frame index in the chain of the text models frames






firstFrame

ItemRef
0

On successful return it contains the first frame of the chain









Get al frames of the current page an log their text frame properties.



int main ()
{
    int 		result;
    ItemList	frames	= itemlist::pageframes (-1);
    int 		len		= itemlist::length (frames);
    ItemRef		frame	= item::alloc ();
    ItemRef		frame1	= item::alloc ();
    int			i		= 0;
    int 		a, b, idx;

    while (i < len)
    {
        itemlist::get (frames, frame, i++);
        wlog ("", "# Frame %d : ", item::getint (frame));
        if (frame::is_textframe (frame, &a, &b, &idx, frame1))
        {
            wlog ("", "%d text frame [%d, %d], first %d\n",
            idx+1,
            a, a+b,
            item::getint (frame1));
        }
        else	wlog ("", "not a text frame\n");
    }

    return 0;
}


Version 1.3.4, R172
startPos, length and idx, firstFrame since version 2.1 R1166, 26. Feb. 2009





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







frame::is_graphicframe
is_textframe
is_guide
is_standoff

comet.CPageItem.getType








static   int is_guide(ItemRef frame)



Is the frame a "guide layer"?







Name
Type
Default
Description





Return

int
 

1 : Yes

0 : No






frame

ItemRef
-

valid frame







Version 1.3.4, R172





priint:comet InDesign® Plug-Ins





frame::is_graphicframe
is_textframe
is_guide
is_standoff

comet.CPageItem.getType








static   int is_standoff(ItemRef frame)



Is the frame a  "stand off"?







Name
Type
Default
Description





Return

int
 

1 : yes

0 : no






frame

ItemRef
-

valid frame







Version 1.3.4, R172





priint:comet InDesign® Plug-Ins





frame::is_graphicframe
is_textframe
is_guide
is_standoff








static   int is_textinset(ItemRef frame)



Is the frame a  "text inset"?







Name
Type
Default
Description





Return

int
 

1 : yes

0 : no






frame

ItemRef
-

valid frame







Version 1.3.4, R172





priint:comet InDesign® Plug-Ins





frame::is_graphicframe
is_textframe
is_guide
is_standoff








static   int is_group(ItemRef frame)



Is the frame a  group?







Name
Type
Default
Description





Return

int
 

1 : yes

0 : no






frame

ItemRef
-

valid frame







Version 1.3.4, R172





priint:comet InDesign® Plug-Ins, Illustrator





frame::is_graphicframe
is_textframe
is_guide
is_standoff

comet.CPageItem.getType








static   int is_media(ItemRef frame)



Is the frame a media object?







Name
Type
Default
Description





Return

int
 

1 : yes

0 : no






frame

ItemRef
-

valid frame







Version 1.3.4, R172





priint:comet InDesign® Plug-Ins



frame::is_graphicframe
is_textframe
is_guide
is_standoff








static   int is_qrcode(ItemRef frame)



Does the frame contain a QR code?




Only frames are recognised as QR codes if their QR code was created by
image::qrcode or by the menu command Object -> Generate QR Code....







Name
Type
Default
Description





Return

int
 

1 : Yes

0 : No






frame

ItemRef
-

Valid frame reference







v4.1.8 R27646, 20. Oct. 2020






priint:comet InDesign® Plug-Ins







image::qrcode

comet.CPageItem.getType







static   char* get_script_tag(ItemRef frame, char*  key = "Label")



Find the value of a script tag of a frame.







Name
Type
Default
Description





Return

char*
 

Value of script tag

The return value is read only, do NOT CHANGE.
The result will be overridden on following calls to the function.
See here to learn more about functions returning r/o char* values.







frame

ItemRef
-

valid document frame






key

String or char*
"Label"

"Label" : Get the value shown in the panel  Window:Automation:Script Label


otherwise : The value set by a prior call to set_script_tag for the given key










int main ()
{
    showmessage ("Skriptlabel : '%s'.", frame::get_script_tag (gFrame));

    frame::set_script_tag (gFrame, "Hallo Paul");
    frame::set_script_tag (gFrame, "Paul", "Ich");

    showmessage ("Skriptlabel (Neu): '%s'.", frame::get_script_tag (gFrame));
    showmessage ("Value of Ich: '%s'.", frame::get_script_tag (gFrame, "Ich"));

    return 0;
}


Version 1.4 R 330, 3. Apr. 2007





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







comet.CPageItem.getScriptTag








static   int count_script_tags(ItemRef frame)



Count the number of defined script labels of a given frame.




Standard labels used by InDesign® and the priint:priint:comet InDesign® Plug-Ins are not counted!







Name
Type
Default
Description





Return

int
 

Number of script labels


0 : No script labels or error






frame

ItemRef
-

Valid document frame







Version v4.1 R21778, 16. Feb 2018





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





get_nth_script_tag

comet.CPageItem.getScriptTags








static   int get_nth_script_tag(
 	ItemRef frame,
 	int nth,
 	char*  key,
 	char*  value)



Get the nth key/value pair of the script labels of a given frame.




Standard labels used by InDesign® and the priint:priint:comet InDesign® Plug-Ins are ignored by the function!







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frame

ItemRef
-

Valid document frame






nth

int
-

Valid index of script label






key

String oder char*
-

Allocated String or char* for the key






value

String oder char*
-

Allocated String or char* for the value










int main ()
{
    String		key = string::alloc ();
    String		value = string::alloc ();
    int 		n;

    for (n = 0; n < frame::count_script_tags (gFrame); n++)
    {
        frame::get_nth_script_tag (gFrame, n, key, value);
        wlog ("", "  %d	: '%s' : '%s'\n", n, key, value);
    }

    string::release (key);
    string::release (value);

    return 0;
}


Version v4.1 R21778, 16. Feb 2018





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







count_script_tags

comet.CPageItem.getScriptTags








static   int set_script_tag(
 	ItemRef frame,
 	char*  value,
 	char*  key = "Label",
 	int type = 0)



Set the value of a script tag of a frame.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frame

ItemRef
-

Valid document frame






value

String or char*
-

New value (its allowed to set "" or 0 here)






key

String or char*
"Label"

"Label" : Set the value shown in the panel  Window:Automation:Script Label






type

int
0

Data type of the entry. This information is used only by Illustrator®!


kInt = 1 : Integer


kFloat = 2 : Decimal point


kBool = 4 : Bool

The following input values are supported besides number strings: "true", "kTrue, "yes", "false", "kFalse", "no".
The value of the entry is set to "1" or "0" accordingly always.



otherwise : String


Please note that the value value
Likewise, with get_script_tag and get_nth_script_tag you always get the value as string!





  #include "internal/types.h"





Set an individual image counter to the selected frame:



int main ()
{
    char		v	[512];

    strcpy (v, frame::get_script_tag (gFrame, "Image number"));
    if (!askstring (v, "Integer number", "Image number", 0, 0, 0)) return 0;
    frame::set_script_tag (gFrame, v, "Image number");

    return 0;
}



Parameter type since v4.1.8 R27590, 5. Oct 2020
Version 1.4 R 330, 3. Apr. 2007





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







comet.CPageItem.setScriptTag








static   int set_origin(ItemRef frame)



The call is part of the document synchronization. Frames of variant documents that have an equivalent in the master
document are containing these UIDs in the so called Origin-ID. Locally created frame of
the variant have the Origin-ID 0. Based on this information, the synchronization can recognize whether and from which frame
changes are to be taken from the master document. If the frame UIDs are displayed in the document, the Origin ID
is shown next to the UID:









Here the frame with the UID 300 of the varaiant points to the frame (also) with the UID 300 of the master document.
In the course of time, different changes to variant and master will result in frames whose origin ID is considerably different from the
local UID.



How to enable the display of frame UIDs:

    

  1. Open the context menu in the document with CTRL-click or right mouse button

  2. Choose menue Nails and Magnets - > Show

  3. Again open the context menu in the document with CTRL-click or right mouse button

  4. Choose menue Nails and Magnets - > Show Frame UIDs








Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frame

ItemRef
-

Valid document frame







v4.1.6 R26001, 30. Sep 2019





priint:comet InDesign® Plug-Ins, comet_pdf







get_origin
document::create_variant








static   int get_origin(ItemRef frame)



Get the UUID of the frame.







Name
Type
Default
Description





Return

int
 

Current Origin-ID of frame


0 : Not set or error






frame

ItemRef
-

Valid document frame







v4.1.6 R26001, 30. Sep 2019





priint:comet InDesign® Plug-Ins, comet_pdf







set_origin
document::create_variant








static   int remove_image(ItemRef frameRef)



Delete an image of a grafic frame







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frame

ItemRef
-

valid document frame







Version 1.4 R 297





priint:comet InDesign® Plug-Ins, comet_pdf













static   int remove_redundant_tags(
 	ItemRef frameref = 0,
 	int startPos = 0,
 	int len = -1)


Clean up textplaceholders. Text attribut changes such as font, textsize, color, ... are breaking the Comet placeholders into several so called
runs. The Comet plug ins are runs save. But for templates and document templates it would be a good idea, to remove this redundant
information for performance reasons.




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




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







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
0

Valid text frame


0 : script frame






startPos

int
0

text start position






len

int
kEnd

Length of text to work on or  kEnd, kSelection


With kSelection you can run over the script limitations and chang esome unexpected text.





  #include "internal/text.h"


Version 1.4.1 R417, 24. Jul 2007





priint:comet InDesign® Plug-Ins







textmodel::remove_redundant_tags
textmodel::gremove_redundant_tags
document::remove_redundant_tags








static   int set_objectstyle(
 	ItemRef frameRef,
 	char*  stylePath,
 	int applyEmptyCatWithRoot = 0,
 	int clearOverrides = 0)



Apply object style to a frame. ':' is used as path delimiter for style folders used since CS4. Styles and folders therefor must not contain ':'s.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

valid frame


0 : script frame






stylename 

String or char*
-

style (path and) name. ':' is used as path delimiter. Standard style names can accepted in English and in the language of the current InDesign® version.


"" : Set current default object style for the frame type (text or graphic)






applyEmptyCat

int
0

This is an InDesign®-API wrapper. The API contains the following description : "1 if we are applying empty (unchecked) cateogories from the root style" - may it be helpfull :-)






clearOverrides

int
0

+-Remover


0 : Keep overrides

1 : Clear overrides







Version 1.4.2 R612, 14. Mar 2008

clearOverrides since v3.2.3 R2630, 5. Sept. 2011

stylePath = "" since v3.2.3 R2630, 5. Sept. 2011





priint:comet InDesign® Plug-Ins, comet_pdf





get_objectstyle

comet.CPageItem.setObjectStyle








static   char* get_objectstyle(ItemRef frameRef)



Retreive (path and) name of a frames object style.







Name
Type
Default
Description





Return

char*
 

(Path and) name of the object style applied to the frame

"" : No style set or error or InDesign version prior CS3

The return value is read only, do NOT CHANGE.
The result will be overridden on following calls to the function.
See here to learn more about functions returning r/o char* values.







frameRef

ItemRef
-

valid frame


0 : script frame






doTranslate

int
0

Translate standard names?


0 : No. In this case, the names of the standard styles are always returned in English. In a German InDesign® this means:

    

  • "[Ohne]"	--> "[None]"

  • "[Einfacher Grafikrahmen]"	--> "[Normal Graphics Frame]"

  • "[Einfacher Textrahmen]"	--> "[Normal Text Frame]"





1 : Translate standard names into the language of the current InDesign®







v3.2.3 R2630, 5.Sept. 2011

Parameter doTranslate seit v3.4 R5627, 27. Aug 2014





priint:comet InDesign® Plug-Ins, comet_pdf





set_objectstyle

comet.CPageItem.getObjectStyle








static   int insert_crossref(
 	 int index,
 	int len,
 	char*  name,
 	int classid = 0,
 	int id = 0,
 	int id2 = 0,
 	int id3 = 0,
 	char*  sid = "",
 	int borderVisble = 0,
 	int borderWidth = 1,
 	int borderHilite = 3,
 	int borderStyle = 1,
 	float borderCol1 = -1.0,
 	float borderCol2 = -1.0,
 	float borderCol3 = -1.0,
 	float borderCol4 = -1.0,
 	int*  delBefore = 0)



Insert a cross reference destination into a text. This destination are not allowed to overlap different Comet placeholders. It is strongly recommanded to
use 0 as the destinations length, but you can use longer destinations if you want. A cross reference destination will insert one (invisible, but existing) character into the text.
Position is relative to the text in frameRef.



A detailed description about Comet cross references you will find here.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Valid text frame

0 : Current script frame






index

int
-

placeholder relative position of the cross reference destination






len

int
-

Number of characters occupied by destination. It is strongly recommanded to
use 0 as the destinations length! But if you want ... .






name

String or char*
-

reference name


"" : Cross reference is used as the name






classid

int
0

Class number of the object






id, id2, id3

int
0

object IDs






sid

String or char*
""

StringID of the object






borderVisble

int
0

visible in document?


0 : No

1 : Yes






borderWidth

int
1

Frame width


1 : Thin

2 : Middle

3 : Bold






borderHilite

int
3

Frame type

1 : Draw reference inverted (Not supported inInDesign® , but visible in PDF export.)

2 : Inset

3 : Outline






borderStyle

int
1

Frame border style. InDesign® only supports the following two values:

0 : Continuous

1 : Dashed






borderCol1, borderCol2, borderCol3, borderCol4

float
-1.0

Frame color in the range of 0.0 - 100.0 (or -1.0).


First three defined : use RGB

Four defined colors - use CMYK (don't work for now, sorry)

otherwise : Orange






delBefore

int*
1

Attention : Its an address!. Automatically remove a reference of same name and Comet ID at
the insertion point index. On return it contains whether a reference was deleted (1) or not (0).









You will find an example under textmodel::insert_crossref. Cross references to frames will work in same way.





Version 2.1 R668, 14. April 2008





priint:comet InDesign® Plug-Ins







textmodel::insert_crossref
document::update_crossrefs
hyperlink::find
hyperlink::find1
link
w2cross-Tag

comet.CTextModel.insertCrossRef








static   int getbbox_before_adapt(
 	ItemRef frameRef,
 	float*  fbox_l = 0,
 	float*  fbox_t = 0,
 	float*  fbox_r = 0,
 	float*  fbox_b = 0,
 	float*  ibox_l = 0,
 	float*  ibox_t = 0,
 	float*  ibox_r = 0,
 	float*  ibox_b = 0)



Get the original bounding boxes of a frame before the current page adaption was started. In situations outside the page adaption, the function will return an error. in case of text frames, the image box values are empty.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Valid frame reference






fbox_l, fbox_t, fbox_r, fbox_b

float*
0

Original bounding box of the document frame  in points (left, top, right, bottom)






ibox_l, ibox_t, ibox_r, ibox_b

float*
0

Original bounding box of the image frame relativ to the document frame in points (left, top, right, bottom). Bei Textrahmen erhalten Sie die Werte 0.0.







Version 2.1 R714, 19. Mai 2008





priint:comet InDesign® Plug-Ins, comet_pdf











static   int get_display_details(
 	ItemRef frameRef,
 	int what,
 	int stripWidths = 1,
 	float*  l = 0,
 	float*  t = 0,
 	float*  r = 0,
 	float*  b = 0)



Find out the page adaption image details. The functions returns an error in case of text frames.








Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Valid Graphic Frame reference






what

int
-

What kind of details?


0 : Image details 1 (minimum)

1 : Image details 2 (maximum)






stripWidths

int
1

1 : Results contain the size of the protected strips. Values are given in points from the unscaled image.


0 : Results contain the remaining image area in points in respect to current current image scaling relativ to the image frame.
With an image of 300 x 300 points and 100 point wide strips on every side, the remaining rectangle is then 100, 100, 200, 200. With scale factor 50%
in x and y direction, the result would be 50, 50, 100, 100.







l, t, r, b

float*
0

results in points







Version 2.1 R714, 16. Mai 2008





priint:comet InDesign® Plug-Ins











static   int apply_display_details(
 	 ItemRef frameRef,
 	int refPoint,
 	int xposMethod = 1,
 	int yposMethod = 1,
 	int canChangeLeft = 1,
 	int canChangeTop = 1,
 	int canChangeRight = 1,
 	int canChangeBottom = 1)



Apply the display details given in the Page adaption. The function has no effect on text frames.





In the Page adaption panel you can define two display details for any image.









The inner part of the image should be visible in any situation. The green parts are optional, the orange parts are forbidden.
This a call to apply_display_details you change the frames size to satisfy this conditions. To pin the frame at one position, use refPoint.




Changing the frame size in respect to the given display details can change the nail fixed distances of an image frame.





After the page adaption has changed a frame size (and before applying the display details}), you may wish to reposition the image. Use xposMethod and yposMethod
in this case:



Value
Description
Comments




kIgnore
No reposition needed





kRequiredStrips, kForbiddenStrips

Use the current strip arrangment to reposition the image. If, for example, from the left green strip 10 points are visible before
the resizing and from right side 20 points and the frame was resized by 9 points, the image is moved 3 points left.

On calls inside a page adaption only




kRequiredStripsUniform, kForbiddenStripsUniform

The strips on both sides are equal, no matter on their former widths. The center between the strips becomes the center of image.
If, for example, the image frame is 9 points bigger than the minimum allowed image size, the image is positioned at 4.5 points.






kRequiredStripsProp, kForbiddenStripsProp

Position the image in respect to the given strip widths. If, for example, the left strip is 10 points wide and the right 20 points and
the image frame is 9 points bigger, the image is posioned at 3 points no matter how the image was positioned before.












Name
Type
Default
Description





Return

int
 

0 oder Fehlercode






frameRef

ItemRef
-

Referenz auf einen Grafikrahmen






refPoint

int
kRefPointTopLeft

In Inlinerahmen wird die Angabe ignoriert. Referenzpunkt der Skalierung


kRefPointTopLeft

kRefPointTopCenter

kRefPointTopRight

kRefPointLeftCenter

kRefPointCenter

kRefPointRightCenter

kRefPointBottomLeft

kRefPointBottomCenter

kRefPointBottomRight


kRefPointNone






xposMethod, yposMethod

int
kRequiredStrips

Image positioning, see table below


kIgnore

kRequiredStrips

kForbiddenStrips

kRequiredStripsUniform

kForbiddenStripsUniform

kRequiredStripsProp

kForbiddenStripsProp






canChangeLeft, canChangeTop, canChangeRight, canChangeBottom

int
1

Enable/Disable frame resizing at the given frame side. Required/Forbidden image parts
can become invisible/visible in case of suppressing.





  #include "internal/text.h"

  #include "internal/types.h"


Version 2.1 R714, 20. Mai 2008





priint:comet InDesign® Plug-Ins













static   int get_nail(
 	 ItemRef frameRef,
 	int refPoint,
 	int*  preferMax = 0)



Is an edge or a side of a frame nailed by the page adapting tool?







Name
Type
Default
Description





Return

int
 

0 : no nail or error

1 : nail

2 : percent nail

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

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






frameRef

ItemRef
-

valid frame reference






refPoint

int
-

kRefPointTopLeft

kRefPointTopCenter

kRefPointTopRight

kRefPointLeftCenter

kRefPointRightCenter

kRefPointBottomLeft

kRefPointBottomCenter

kRefPointBottomRight







preferMax

int*
0

1 : on edge nails which prefers the maximum size change

0 : otherwise





  #include "internal/types.h"





int preferMax;

wlog ("", "Nail top left	 : %d (%d)\n",
 	frame::get_nail (gFrame, kRefPointTopLeft, &preferMax),
 	preferMax);
wlog ("", "Nail top : %d (%d)\n",
 	frame::get_nail (gFrame, kRefPointTopCenter, &preferMax),
 	preferMax);
wlog ("", "Nail top right : %d (%d)\n",
 	frame::get_nail (gFrame, kRefPointTopRight, &preferMax),
 	preferMax);

wlog ("", "Nail left : %d (%d)\n",
 	frame::get_nail (gFrame, kRefPointLeftCenter, &preferMax),
 	preferMax);
wlog ("", "Nail right : %d (%d)\n",
 	frame::get_nail (gFrame, kRefPointRightCenter, &preferMax),
 	preferMax);

wlog ("", "Nail bottom left : %d (%d)\n",
 	frame::get_nail (gFrame, kRefPointBottomLeft, &preferMax),
 	preferMax);
wlog ("", "Nail bottom : %d (%d)\n",
 	frame::get_nail (gFrame, kRefPointBottomCenter, &preferMax),
 	preferMax);
wlog ("", "Nail bottom right : %d (%d)\n",
 	frame::get_nail (gFrame, kRefPointBottomRight, &preferMax),
 	preferMax);



Version 2.1 R835, 28. July 2008





priint:comet InDesign® Plug-Ins, comet_pdf







incoming_magnets
outgoing_magnets
apply_magnets

incoming_magnets
outgoing_magnets

comet.CFrame.getNail








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



Set or remove priint:adjust nails.




Internal use only!




You may use this function, but please note that the function is not covered by support.








Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Valid frame reference


0 : current script frame






refPoint

int
-

kRefPointTopLeft

kRefPointTopCenter

kRefPointTopRight

kRefPointLeftCenter

kRefPointRightCenter

kRefPointBottomLeft

kRefPointBottomCenter

kRefPointBottomRight






type

int
-1

0 : Remove

1 : Normal (green) nail

2 : Relative (red) nail

-1 : Toggle






preferMax

int
0

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


0 : prefer shorter side

1 : prefer longer side





  #include "internal/types.h"


v4.0.5, R10330, 11. Mar 2016





priint:comet InDesign® Plug-Ins, comet_pdf







get_nail

comet.CFrame.setNail








static   int set_magnet(
 	 ItemRef fromRef,
 	int fromSide,
 	ItemRef toRef = 0,
 	int toSide = -1,
 	int type = 0,
 	int isWhite = 0,
 	int canAlt = 0)



Set or remove magnets for priint::adjust.




span[memo4]{Internal use only!}




You may use this function, but pleae note that the function in not subject of any support.








Name
Type
Default
Description





Return

int
 

0 or ErrorCode






fromRef

ItemRef
-

Valid frame reference for magnet source


0 : Current script frame






fromSide

int
-

Start side


0 : left

1 : top

2 : right

3 : bottom






toRef

ItemRef
0

Valid frame reference for magnet destination. Ignored in csse of removing magnets.






toSide

int
-1

Destination side


0 : left

1 : top

2 : right

3 : bottom






type

int
0

0 : Remove

3 : Normal (green) magnet

4 : Relative (red) magnet


Ask frame::get_magnet_type to get the type of a magnet.






isWhite

int
0

0 : Normal frame magnet

1 : Magnet to the image of the frame






canAlt

int
0

0 : Replace existing magnet(s) to the destination


1 : If a magnet to the destination exists already, add the new one as an alternative.









Redirect (vertical) magnets from source to dest(s) before removing a frame.



int main ()
{
    List		in		= list::alloc ();
    List		out		= list::alloc ();
    ItemRef		fr_in	= item::alloc ();
    ItemRef		fr_out	= item::alloc ();
    int			magRef, magType, magWhite;
    int			i;

    frame::incoming_magnets (in, gFrame, 1);
    if (list::length (in) > 0)
    {
        frame::get_magnet_reference (fr_in, gFrame, list::get (in, 0));

        frame::outgoing_magnets (out, gFrame, 3);

        for (i = 0; i < list::length (out); i++)
        {
            magRef	= list::get (out, i);

            frame::get_magnet_reference (fr_out, gFrame, magRef);
            magType		= frame::get_magnet_type (gFrame, magRef);
            magWhite	= frame::get_magnet_is_white (gFrame, magRef);

            if (magType)
            {
                frame::set_magnet (
                 	fr_in, 3,
                 	fr_out, 1,
                 	magType,
                 	magWhite,
                 	0);
            }
        }
    }

    frame::remove (gFrame);
    return 0;
}





Transfer magnets from one frame (here we take the frame with the UID 229) to another frame (gFrame in example) and finally remove
the frame.



int main ()
{
    List		in		= list::alloc ();
    List		out		= list::alloc ();
    ItemRef		fr		= item::alloc ();
    ItemRef		fr_in	= item::alloc ();
    ItemRef		fr_out	= item::alloc ();
    int			magRef, magType, magWhite;
    int			i;

    item::define (fr, gFrame, 229);

    frame::incoming_magnets (in, fr, 1);
    if (list::length (in) > 0)
    {
        magRef	= list::get (in, i);
        frame::get_magnet_reference (fr_in, fr, magRef);
        frame::set_magnet (
         		fr_in, 3,
         		gFrame, 1,
         		frame::get_magnet_type (0, magRef),
         		frame::get_magnet_is_white (0, magRef),
         		0);
    }

    frame::outgoing_magnets (out, fr, 3);
    for (i = 0; i < list::length (out); i++)
    {
        magRef	= list::get (out, i);
        frame::get_magnet_reference (fr_out, gFrame, magRef);
        wlog ("", "TTT %d\n", frame::get_magnet_type (0, magRef));
        frame::set_magnet (
         		gFrame, 3,
         		fr_out, 1,
         		frame::get_magnet_type (0, magRef),
         		frame::get_magnet_is_white (0, magRef),
         		0);
    }

    frame::remove (fr);

    return 0;
}


v4.0.5, R10330, 11. Mar 2016





priint:comet InDesign® Plug-Ins, comet_pdf







set_nail
incoming_magnets
outgoing_magnets
get_magnet_reference
get_magnet_type
get_magnet_is_white

comet.CFrame.setMagnet








static   int incoming_magnets(
 	List resultList,
 	ItemRef frameRef,
 	int side)



Get all incoming magnets of one given side of a frame.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






resultList

List
-

Allocated result list. On successful return it contains references to the magnets found at the given side of the frame.
Use this values in subsequent calls to get_magnet_type, get_magnet_is_white, get_magnet_is_rotation_only and get_magnet_reference.






frameRef

ItemRef
-

Valid frame reference


0 :current script frame






side

int
-

Side of interest


0 : left

1 : top

2 : right

3 : bottom









Write all magnets to the top and from the bottom of a given frame to the logfile.



int main ()
{
    List	magnets	= list::alloc ();
    ItemRef	item	= item::alloc ();
    int	i;
    int	res;

    res = frame::incoming_magnets (magnets, gFrame, 1);
    wlog ("", "incomings @ top : %d (result = %d)\n", list::length (magnets), res);
    for (i = 0; i < list::length (magnets); i++)
    {
        frame::get_magnet_reference (item, gFrame, list::get (magnets, i));
        wlog ("", "	%d : %d\n", i+1, item::getint (item));
    }

    frame::outgoing_magnets (magnets, gFrame, 3);
    wlog ("", "outgoings @ bottom : %d (result = %d)\n", list::length (magnets), res);
    for (i = 0; i < list::length (magnets); i++)
    {
        frame::get_magnet_reference (item, gFrame, list::get (magnets, i));
        wlog ("", "	%d : %d\n", i+1, item::getint (item));
    }

    return 0;
}





Let a frame change the width of its magnet parent. (Impossible with magnets because of a magnet circuit.) You  may use this script
as an adapter action of the child frame. I would prefer the situation "After adaption", but its up to you.



int main ()
{
    List		magnets	= list::alloc ();
    ItemRef		item	= item::alloc ();
    int			res;
    float		l1, t1, r1, b1;
    float		l2, t2, r2, b2;

    res = frame::incoming_magnets (magnets, gFrame, 1); // oben
    if (res)							return 0;
    if (list::length (magnets) == 0)	return 0;

    frame::get_magnet_reference (item, gFrame, list::get (magnets, 0)); // Hauptmagnet
    frame::bbox (gFrame,	&l1, &t1, &r1, &b1);
    frame::bbox (item, 		&l2, &t2, &r2, &b2);
    if (r1-l1 < 10.0)	return 0;
    if (b2-t2 < 10.0)	return 0;

    frame::resize (item, r1-l1, b2-t2);

    return 0;
}



Version 3.2 R2250, 27. Jan. 2011





priint:comet InDesign® Plug-Ins, comet_pdf







get_nail
get_magnet_type
get_magnet_is_white
get_magnet_is_rotation_only
get_magnet_reference
apply_magnets

comet.CFrame.getIncomingMagnets








static   int outgoing_magnets(
 	List resultList,
 	ItemRef frameRef,
 	int side)



Get all outgoing magnets of one given side of a frame.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






resultList

List
-

Allocated result list. On successful return it contains references to the magnets found at the given side of the frame.
Use this values in subsequent calls to get_magnet_type, get_magnet_is_white, get_magnet_is_rotation_only and get_magnet_reference.






frameRef

ItemRef
-

Valid frame reference


0 : Current script frame






side

int
-

Side of interest


0 : left

1 : top

2 : right

3 : bottom









Write all magnets to the top and from the bottom of a given frame to the logfile.



int main ()
{
    List	magnets	= list::alloc ();
    ItemRef	item	= item::alloc ();
    int		i;
    int		res;

    res = frame::incoming_magnets (magnets, gFrame, 1);
    wlog ("", "incomings @ top : %d (result = %d)\n", list::length (magnets), res);
    for (i = 0; i < list::length (magnets); i++)
    {
        frame::get_magnet_reference (item, gFrame, list::get (magnets, i));
        wlog ("", "	%d : %d\n", i+1, item::getint (item));
    }

    frame::outgoing_magnets (magnets, gFrame, 3);
    wlog ("", "outgoings @ bottom : %d (result = %d)\n", list::length (magnets), res);
    for (i = 0; i < list::length (magnets); i++)
    {
        frame::get_magnet_reference (item, gFrame, list::get (magnets, i));
        wlog ("", "	%d : %d\n", i+1, item::getint (item));
    }

    return 0;
}


Version 3.2 R2250, 27. Jan. 2011





priint:comet InDesign® Plug-Ins, comet_pdf







get_nail
get_magnet_type
get_magnet_is_white
get_magnet_is_rotation_only
get_magnet_reference
apply_magnets

comet.CMagnet.getOutgoingMagnets








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

comet.CMagnet.getType








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

comet.CMagnet.isImage








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

1 : Rotation






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

comet.CMagnet.isRotationOnly








static   int get_magnet_reference(
 	ItemRef resultRef,
 	ItemRef frameRef,
 	int magnetRef)



Is a given magnet used in format adaption or in page rotations?







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






resultRef

ItemRef
-

allocated variable for the resulting frame






frameRef

ItemRef
-

valid frame reference


0 : current script frame




Unlike the functions frame :: get_magnet_type ... the frame reference is actually needed here: it is necessary to complete the definition result reference.






magnetRef

int
-

magnet reference

You may get magnet references by the functions incoming_magnets und outgoing_magnets.









Let a frame change the width of its magnet parent. (Impossible with magnets because of a magnet circuit.) You  may use this script
as an adapter action of the child frame. I would prefer the situation "After adaption", but its up to you.



int main ()
{
    List	magnets	= list::alloc ();
    ItemRef	item	= item::alloc ();
    int		res;
    float	l1, t1, r1, b1;
    float	l2, t2, r2, b2;

    res = frame::incoming_magnets (magnets, gFrame, 1); // top side
    if (res)							return 0;
    if (list::length (magnets) == 0)	return 0;

    frame::get_magnet_reference (item, gFrame, list::get (magnets, 0)); // main magnet
    frame::bbox (gFrame,	&l1, &t1, &r1, &b1);
    frame::bbox (item, 		&l2, &t2, &r2, &b2);
    if (r1-l1 < 10.0)	return 0;
    if (b2-t2 < 10.0)	return 0;

    frame::resize (item, r1-l1, b2-t2);

    return 0;
}


Version 3.2 R2250, 27. Jan. 2011





priint:comet InDesign® Plug-Ins, comet_pdf







get_nail
get_magnet_type
get_magnet_is_white
get_magnet_is_rotation_only
apply_magnets








static   int inline_(
 	ItemRef textFrameRef,
 	int pos,
 	ItemRef frameRef = 0,
 	int flag = 1,
 	float yoff = 0.0,
 	int lock = 0)



Change a frame to a text inline or anchored frame.







Name
Type
Default
Description





Return

int
 

0 or Error rcode






textFrameRef

ItemRef
-

valid frame reference






pos

int
-

Text position for inline






frameRef

ItemRef
0

Frame to inline. May be empty if flag = 2


On successful return it contains the new frame reference.


Changed on successful return!






flag

int
1

What to do, if an inline exists at the given position already?


0 - create anyway

1 - delete an recreate

2 - do not create, but change






yoff

float
0.0

y-offset given in points






lock

int
0

Suppress manual changes


0 : no

1 : yes









Import some templates, group an inline them.



#include "internal/text.h"
#include "internal/types.h"

int main ()
{
    DataPool	pool	= datapool::alloc ();
    ItemList	frames	= itemlist::alloc ();
    ItemRef		groupRef= item::alloc ();
    ItemList	items	= 0;
    float		l		= 0.0;
    float		t		= 0.0;
    float		r, b;
    int			i;
    int			textpos	= 200;
    int			res;

    if (!textmodel::available ()) return 0;

    // Insert some frames
    // You must have any templates 41 and 42 defined
    for (i = 41; i<43; i++)
    {
        // insert template
        // items is allocated automatically
        items = document::place_items (pool, "data", "pageitems", i, l, t);

        // collect inserted frames
        itemlist::appendlist (frames, items);

        // Get frames bbox
        itemlist::bbox (items, &l, &t, &r, &b);
        itemlist::release (items);
        items = 0;

        t = b + 2.0;
    }

    // Group all new frames
    frame::group (frames, groupRef);

    // Make them an inline
    // groupRef will change!
    res = frame::inline_ (
     	gFrame,
     	textpos,
     	groupRef,
     	0,
     	12.3,	// yoff
     	1);	// lock
    wlog ("", "inline_ returns %d\n", res);

    return 0;
}


Version 2.1 R1145, 28. Jan 2009





priint:comet InDesign® Plug-Ins, comet_pdf







frame::inline_above
frame::anchor
frame::get_anchor
inline_
release_inline








static   int inline_above(
 	ItemRef textFrameRef,
 	int pos,
 	ItemRef frameRef = 0,
 	int flag = 1,
 	int halign = 3,
 	float spaceBefore = 0.0,
 	float spaceAfter = 0.0,
 	int lock = 0)



Create an "inline above" frame at a given text position. You may use this function to change the inline properties of an existing frame too.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






textFrameRef

ItemRef
-

Valid text frame reference






pos

int
-

text position to create/change the inline frame






frameRef

ItemRef
0

Frame to convert to an inline. On successful return it contains (the changed) reference to
the new inline. May be empty if flag = 2 ist.






flag

int
1

What to do, if the given text position already points to an inline or anchored object?


0 -create anyway

1 - delete an recreate

2 - change properties only






halign

int
3

horizontal alignment


0 : right

1 : centre

2 : left

3 : text alignment

4 : torwards spine

5 : away from spine






spaceBefore

float
0.0

space before the inline in points






spaceAfter

float
0.0

space after the inline in points






lock

int
0

prevent manual positioning


0 : no

1 : yes









Do import some Comet templates, make one InDesign® group from the imported frames and "inline" this group into a text.



#include "internal/text.h"
#include "internal/types.h"

int main ()
{
    DataPool	pool	= datapool::alloc ();
    ItemList	frames	= itemlist::alloc ();
    ItemRef		groupRef= item::alloc ();
    ItemList	items	= 0;
    float		l		= 0.0;
    float		t		= 0.0;
    float		r, b;
    int			i;
    int			textpos	= 200;
    int			res;

    if (!textmodel::available ()) return 0;

    // Add some frames to the document
    // Templates 41 and 42 must exist!
    for (i = 41; i<43; i++)
    {
        // Insert template
        // items is allocated automatically here
        items = document::place_items (pool, "data", "pageitems", i, l, t);

        // Collec t all insergted frames
        itemlist::appendlist (frames, items);

        // Next template position
        // After that the items list will be released.
        itemlist::bbox (items, &l, &t, &r, &b);
        itemlist::release (items);
        items = 0;

        t = b + 2.0;
    }

    // Grouping imported templates
    frame::group (frames, groupRef);

    // Insert group as inline above frame
    // groupRef ächanges thereby!
    res = frame::inline_above (
     	gFrame,
     	textpos,
     	groupRef,
     	0,	// 0 - Always create, 
     		// 1 - possibly delete and create, 
     		// 2 - create or change
     	4,	// to spline
     	11.1,	// space before
     	22.2,	// space after
     	1);	// lock
    wlog ("", "inline_above returns %d\n", res);

    return 0;
}


Version 2.1 R1145, 28. Januar 2009





priint:comet InDesign® Plug-Ins, comet_pdf







frame::inline_
frame::anchor
frame::get_anchor
inline_above
release_inline








static   int anchor(
 	ItemRef textFrameRef,
 	int pos,
 	ItemRef frameRef = 0,
 	int flag = 1,
 	int spine = 0,
 	int ref_obj = 0,
 	int ref_pt = 3,
 	int xrel = 4,
 	float xoff = 0.0,
 	int yrel = 4,
 	float yoff = 0.0,
 	int keepWithin = 1,
 	int lock = 0)


Make a frame an anchored frame at a text position. You may use this funtion to change the properties of an anchored frame at a given text position too.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






textFrameRef

ItemRef
-

valid text frame






pos

int
-

text position of anchored frame






frameRef

ItemRef
0

Frame to convert to an anchored frame. On successful return it contains (the changed) reference to
the new anchored frame. May be empty if flag = 2 ist.






flag

int
1

What to do, if the given text position already points to an inline or anchored object?


0 -create anyway

1 - delete an recreate

2 - change properties only






spine

int
0

Relative to spine


0 : No

1 : Yes






ref_obj

int
kRefPointTopLeft

Object anchor


kRefPointTopLeft

kRefPointTopCenter

kRefPointTopRight

kRefPointLeftCenter

kRefPointCenter

kRefPointRightCenter

kRefPointBottomLeft

kRefPointBottomCenter

kRefPointBottomRight






ref_pt

int
kRefPointLeftCenter

reference point. Attention : Not all reference points are supported by all frame preferences!


kRefPointTopLeft

kRefPointTopCenter

kRefPointTopRight

kRefPointLeftCenter

kRefPointCenter

kRefPointRightCenter

kRefPointBottomLeft

kRefPointBottomCenter

kRefPointBottomRight






xrel

int
4

x relative to


0 : column edge

1 : text frame

2 : page margin

3 : page edge

4 : anchor marker






xoff

float
0.0

"x-Offset" in points






yrel

int
4

y relativ zu


0 : column edge

1 : text frame

2 : page margin

3 : page edge

4 : line (Baseline)

5 : line (Height of X)

6 : line (Cap height)

7 : line (Botto of Leading)

8 : line (Top of Leading)

9 : Em-Box top

10 : Em-Box centre

11 : Em-Box bottom






yoff

float
0.0

"y-Offset" in points






keepWithin

int
1

Keep within Top/Bottom column boundaries


0 : no

1 : yes






lock

int
0

Prevent manual positioning


0 : no

1 : yes





  #include "internal/types.h"


Version 2.1 R1145, 28. Januar 2009





priint:comet InDesign® Plug-Ins, comet_pdf







inline_
inline_above
get_anchor	
frame::anchor








static   int get_anchor(
 	 ItemRef textFrameRef,
 	int pos,
 	int len,
 	int*  out_pos,
 	int*  out_type = 0,
 	ItemRef out_frameRef = 0,
 	int*  rel_to_spine = 0,
 	int*  refpoint_obj = 0,
 	int*  refpoint_pt = 0,
 	int*  xrel = 0,
 	float*  xoff = 0,
 	int*  yrel = 0,
 	float*  yoff = 0,
 	int*  keepWithin = 0,
 	int*  locked = 0,
 	int*  halign = 0,
 	float*  spaceBefore = 0,
 	float*  spaceAfter = 0,
 	float*  yoff_inline = 0 )



Get the properties of an inline-above or anchored frame. If an object is found at the given text position, the appropriate out varibales for the object type are filled.

Set variables, you do not need to 0.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode
Error code 0 (no error) does NOT mean, that no inline was found at the given position. No object found you can see at out_pos == -1.
kein Inline oder verankerter Rahmen gefunden wurde. Ob ein solches Objekt gefunden wurde, gibt die Variable out_pos == -1 an.}






textFrameRef

ItemRef
-

Valid frame reference

0 : Current script frame






pos

int
-

Search for an inline in the given text range. The range ist given relative to frame, not to the placeholder.






len

int
-

Search for an inline in the given text range (min 1). The range ist given relative to frame, not to the placeholder.

kEnd : end of text






out_pos

int*
0

on return : position of the first inline object

-1 : no inline found in the given range






out_type

int*
0

Object type


0 : Inline

1 : Anchored frame

2 : Inline above






out_frameRef

ItemRef
0

Anchored frame. 0 or allocte before by item::alloc






rel_to_spine

int*
0

Anchored frames only, out_type == 1 Relative to spine?






refpoint_obj

int*
0

Anchored frames only, out_type == 1 Reference point of the object






refpoint_pt

int*
0

Anchored frames only, out_type == 1 Reference point of anchor






xrel

int*
0

Anchored frames only, out_type == 1






xoff

float*
0

Anchored frames only, out_type == 1 x-offset in points






yrel

int*
0

Anchored frames only, out_type == 1






yoff

float*
0

Anchored frames only, out_type == 1 y-offset in points






keepWithin

int*
0

Anchored frames only, out_type == 1 Not not move away from frame






locked

int*
0

out_type == 0 | 1 | 2 






halign

int*
0

Inline aboves only, out_type == 2






spaceBefore

float*
0

Inline aboves only, out_type == 2 given in points






spaceAfter

float*
0

Inline aboves only, out_type == 2 given in points






yoff_inline

float*
0

Inlines only, out_type == 0 y-offset in points





  #include "internal/text.h"




Inspect all inlines of the current script frame.



#include "internal/text.h"
#include "internal/types.h"

int main ()
{
    int 	pos = 0;
    int		type, rel_to_spine, refpoint_obj, refpoint_pt, xrel, yrel, keepWithin;
    int 	locked, halign;
    float	xoff, yoff, yoff2, spaceBefore, spaceAfter;
    ItemRef	inlineRef	= item::alloc ();
    int 	res;

    while (1)
    {
        res = frame::get_anchor (
         	gFrame,
         	pos,
         	kEnd,
         	&pos,			// out_pos
         	&type,
         	inlineRef,
         	// Anchor
         	&rel_to_spine,
         	&refpoint_obj,
         	&refpoint_pt,
         	&xrel, &xoff,
         	&yrel, &yoff,
         	&keepWithin,
         	&locked,
         	// Inline_Above
         	&halign,
         	&spaceBefore,
         	&spaceAfter,
         	// Inline
         	&yoff2);

        if (res != 0 || pos < 0)	break;

        if (type == 0)
        {
            // Inline
            wlog ("", "%d : Inline found (UID = %d)\n", pos, item::getint (inlineRef));
            wlog ("", "\ty-Offset : %f\n", yoff2);
            wlog ("", "\tLocked : %d\n", locked);
        }
        else if (type == 1)
        {
            // Anchor
            wlog ("", "%d : Anchor found (UID = %d)\n", pos, item::getint (inlineRef));
            wlog ("", "\tSpine : %d\n", rel_to_spine);
            wlog ("", "\tRefpoint Object : %d\n", refpoint_obj);
            wlog ("", "\tRefpoint Position : %d\n", refpoint_pt);
            wlog ("", "\tX Relative To : %d\n", xrel);
            wlog ("", "\tX-Offset : %f\n", xoff);
            wlog ("", "\tY Relative To : %d\n", yrel);
            wlog ("", "\tY-Offset : %f\n", yoff);
            wlog ("", "\tKeep Within : %d\n", keepWithin);
            wlog ("", "\tLocked : %d\n", locked);
        }
        else if (type == 2)
        {
            // Inline Above
            wlog ("", "%d : Inline above found (UID = %d)\n", pos, item::getint (inlineRef));
            wlog ("", "\tAlign : %d\n", halign);
            wlog ("", "\tSpace before : %f\n", spaceBefore);
            wlog ("", "\tSpace After : %f\n", spaceAfter);
        }

        pos = pos+1;

    }
    return 0;
}



Version 2.1 R1145, 28. Januar 2009





priint:comet InDesign® Plug-Ins, comet_pdf







frame::inline_
frame::inline_above
frame::anchor
get_anchor








static   int release_inline(
 	ItemRef inlineRef,
 	float new_left = -10000.0,
 	float new_right = -10000.0)



Make an inline a 'normal' frame, i.e. the frame is no longer part of the text then but a page frame.
If the given frame is not an inline, the function returns an error.




Inlines that extend beyond the page can switch the page or fall entirely within the pasteboard by calling the function.








Name
Type
Default
Description





Return

int
 

0 or ErrorCode






inlineRef

ItemRef
-

valid referenz to an inline. You may use get_anchor to squize out such a reference from of a text.


After successful return, inlineRef points to the new non-inline frame.






new_left, new_right

float
-10000.0

New frame position.


-10000.0, -10000.0 or missing : Same position like the inline







Version 2.1, R1789, 1. March 2010

Parameters new_left, new_right since v4.0.5, R10912, 19. Apr 2016

Available for InDesign® Server since v4.0.5 R12022, 11. Jul 2016





priint:comet InDesign® Plug-Ins, comet_pdf







is_inline
get_anchor
anchor
inline_above
inline_ 
textmodel::get_anchor
textmodel::anchor
textmodel::inline_above
textmodel::inline_








static   int lock(ItemRef frameRef = 0)



Protect a frame from manual changes.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
0

Valid frame reference

0 : current script frame







Version 2.1 R1145, 28. Januar 2009





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





unlock
is_locked

comet.CPageItem.setLocked








static   int unlock(ItemRef frameRef = 0)



Allow manual changes to a frame.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
0

Valid frame reference

0 : current script frame







Version 2.1 R1145, 28. Januar 2009





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





lock
is_locked

comet.CPageItem.setLocked








static   int is_locked(ItemRef frameRef = 0)



Is the given frame locked by InDesign® ?







Name
Type
Default
Description





Return

int
 

0 : No

1 : Yes






frameRef

ItemRef
0

Valid frame reference

0 : current script frame







Version 2.1 R1145, 28. Januar 2009





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





lock
unlocked

comet.CPageItem.getLocked








static   int get_cometgroup(ItemRef frameRef, int searchHierarchy = 1)



Get the CometGroup-ID of a frame.







Name
Type
Default
Description





Return

int
 

Comet group ID of the frame or 0






frameRef

ItemRef
-

Valid frame reference

0 : current script frame






searchHierarchy

int
1

1 : Search document hierarchy if the frame has no group ID.









Remove all frames of any sub group of the given frame.

Since Comet 3.1 R1616 you can use the built-in function frame::remove_sub_cometgroups instead.



int remove_subgroups (ItemRef frame)
{
    int 		groupID	= frame::get_cometgroup (gFrame, 0);
    ItemList	group	= 0;
    ItemRef		mb		= item::alloc ();
    int			mbID	= 0;
    int 		i;

    if (groupID == 0) return 0;

    group = itemlist::get_cometgroup_members (0, groupID, 1);
    if (!group)	return 0;

    for (i = 0; i < itemlist::length (group); i++)
    {
        mb	= itemlist::get (group, mb, i);
        mbID	= frame::get_cometgroup (mb, 0);
        if (mbID!=groupID)
        {
            frame::remove (mb);
        }
    }

    return 0;
}


Version 3.0 R 1500, 26. August 2009





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







itemlist::get_cometgroup

comet.CFrame.getCometGroupID








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



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







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Valid frame reference

0 : current script frame






label

String or char*
-

Comet label to search for. Label can set using panel Template-Behavior and must be of length 1.






outMember

ItemRef
0

Allocated ItemRef for the result (may be 0).









Search for the frame with Comet label "A" within the Comet group of gFrame.



int main ()
{
    ItemRef		member	= item::alloc ();

    frame::get_cometgroup_member (gFrame, "A", member);
    wlog ("", "# UID of member '%s' : %d\n", "A", item::getint (member));

    return 0;
}


v3.2.3 R2401, 18.04.2011





priint:comet InDesign® Plug-Ins, comet_pdf







get_cometgroup
itemlist::get_cometgroup_members








static   int remove_sub_cometgroups(ItemRef frameRef)



Remove all frames from any Comet subgroup of a frame.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
0

Valid frame reference

0 : current script frame









Since the function is not available for Comet 2.1, you may use this workaround:



int remove_subgroups (ItemRef frame)
{
    int 		groupID	= frame::get_cometgroup (gFrame, 0);
    ItemList	group	= 0;
    ItemRef		mb		= item::alloc ();
    int			mbID	= 0;
    int 		i;

    if (groupID == 0)	return 0;

    group = itemlist::get_cometgroup_members (0, groupID, 1);
    if (!group)		return 0;

    for (i = 0; i < itemlist::length (group); i++)
    {
        mb	= itemlist::get (group, mb, i);
        mbID	= frame::get_cometgroup (mb, 0);
        if (mbID!=groupID)
        {
            frame::remove (mb);
        }
    }

    return 0;
}


Version 3.1 R1616, 30.10.2010





priint:comet InDesign® Plug-Ins, comet_pdf







get_cometgroup








static   int is_member_of(
 	ItemRef frameRef,
 	int groupID,
 	int searchHierarchy = 1)



Check whether a frame is a member (direct or via sub groups) of the given Comet Group.







Name
Type
Default
Description





Return

int
 

1 : Yes, is a member

0 : No, not a member






frameRef

ItemRef
-

Valid frame reference

0 : current script frame






groupID

int
-

Comet group ID






searchHierarchy

int
1

1 : Search document hierarchy if the frame has no group ID.







Version 3.0 R 1500, 26. August 2009





priint:comet InDesign® Plug-Ins, comet_pdf





itemlist::are_members_of








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



Add a frame to a given Comet Group. If the frame is the parent frame of a group, the complete group is added.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Valid frame reference

0 : current script frame






groupID

int
-

Comet-group ID






invalidateView

int
0

Invalidate view. For preformance reasons, use 0 in build scripts.







Version 3.0 R 1500, 26. August 2009





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





itemlist::add_to_cometgroup

comet.CFrame.setCometGroupID








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



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




If the given Comet Group ID is set to -1, the frame will be deleted from any membership,
otherwise only if it is a member of the given group.








Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Valid frame reference

0 : current script frame






groupID

int
-

Comet-group ID
-1 : Do not check current membership






invalidateView

int
0

Invalidate view. For preformance reasons, use 0 in build scripts.







Version 3.0 R 1500, 26. August 2009





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





itemlist::remove_from_cometgroup
comet.CFrame.removeFromCometGroup








static   int apply_layout_rules(
 	ItemRef frameRef,
 	int what,
 	ItemRef caller = 0,
 	char*  key = 0,
 	char*  callerData1 = 0,
 	char*  callerData2 = 0,
 	int id = 0,
 	int id2 = 0,
 	int id3 = 0,
 	char*  sid = 0)



Execute the layout rules of a frame. You can specify which layout rules should be executed.
If the layout rule type is disabled (by system::suppres_layoutrules or by the plugins in general) these rules are not executed.








Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Valid frame reference

0 : current script frame






what

int
-

Type of layout rules to execute


2  : After loading placeholders

1  : After Create

32  : At product build up

4   : At reorganisation

8   : After geometry changes






caller

ItemRef
0

Only in case of sending events: Reference to sender






key

String or char*
0

Only in case of sending events: Event key






callerData1, callerData2

String or char*, String or char*
"", ""

Only in case of sending events: Additional data for the receiver






id, id2, id3, sid

int, int, int, String or char*
0, 0, 0, ""

For unlinked frames on load rules only you may provide an object ID here.









A frame has a layout rule as described:


If event "from script" then

    showmessage ("Hallo");

End


A second frame executes the following script. This will show the message provided by the first frame.



int main ()
{
    ItemRef        receiver    = item::alloc ();

    item::define (receiver, gFrame, 222);// 222 - uid of first frame
    frame::apply_layout_rules (receiver, 15, gFrame, "from script");

    return 0;
}



Version 3.1, R1550, 18. Sept. 2009

Parameter caller, keycallerData1, callerData2, id, id2, id3, sid since v3.3 R3388, 7. Jan. 2013





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







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

comet.CFrame.applyLayoutRules








static   int set_top_options(
 	ItemRef frameRef = 0,
 	int textAlign = 4,
 	int pathAlign = 3,
 	int effectType = 1,
 	int overlapOffset = 0,
 	int flip = 0)



Set the (text on path) options.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Valid document frame with text on path 

0 : current script frame






textAlign

int
4

Text alignment - one oth the following values. Do not use other values!


1 : Ascender

2 : Descender

3 : Center

4 : Base line

5 : Above right Em box

6 : Below left Em box

7 : Above right ICF box

8 : Below left ICF box






pathAlign

int
4

Path alignment - one oth the following values. Do not use other values!


1 : Top

2 : Bottom

3 : Center






effectType

int
4

Effekt - one oth the following values. Do not use other values!


1 : Rainbow

2 : Skew

3 : 3D Ribbon

4 : Stair step

5 : Gravity






overlapOffset

int
0

A vaue between -800 und 800.Do not use other values!






flip

int
0

Flip text?


0 : No

1 : Yes







Version 2.1 R1611, 19. Oct 2009





priint:comet InDesign® Plug-Ins







is_textonpath







int get_z_order(ItemRef frameRef, int respectTo)



Get the Z order of a given frame. If the given item is a group, the group is treated as one object, all other grouped frames are handled as single objects.







Name
Type
Default
Description





Return

int
 

<=0 : Error

otherwise : 1-based Z order of the given frame. Frames more in the background have bigger Z orders.






frameRef

ItemRef
-

Valid frame reference

0 : current script frame






respectTo

int
0

0 :Get the Z order in respect to all frames of the spread

1 : Use only the intersecting frames to get the Z order.









Information about the Z order.



int main()
{
    wlog ("", "Z-Order (page rel) : %d\n", 	frame::get_z_order (gFrame, 0));
    wlog ("", "Z-Order 		: %d\n", 	frame::get_z_order (gFrame, 1));
    wlog ("", "in front 	: %d\n", 	frame::is_in_front (gFrame));
    wlog ("", "at back 		: %d\n", 	frame::is_at_back (gFrame));

    return 0;
}


Version 3.1 R1723, 3. Feb. 2010





priint:comet InDesign® Plug-Ins, comet_pdf







is_in_front
is_at_back
itemlist::intersections

comet.CPageItem.getZOrder








static   int bring_to_front(ItemRef frameRef)



Bring the frame to the front of its page.


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








Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Valid frame reference

0 : current script frame







Version 3.1 R1723, 3. Feb. 2010





priint:comet InDesign® Plug-Ins, comet_pdf





comet.CPageItem.moveToFront








static   int bring_forward(ItemRef frameRef)



Bring forward the frame for one Z-layer.


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







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Valid frame reference

0 : current script frame







Version 3.1 R1723, 3. Feb. 2010





priint:comet InDesign® Plug-Ins, comet_pdf





comet.CPageItem.moveForward








static   int send_backward(ItemRef frameRef)



Send backward the frame for one Z-layer.


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








Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Valid frame reference

0 : current script frame







Version 3.1 R1723, 3. Feb. 2010





priint:comet InDesign® Plug-Ins, comet_pdf





comet.CPageItem.moveBackward








static   int send_to_back(ItemRef frameRef)



Send a frame to the back.


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







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Valid frame reference

0 : current script frame







Version 3.1 R1723, 3. Feb. 2010





priint:comet InDesign® Plug-Ins, comet_pdf





comet.CPageItem.moveToBack








static   int is_in_front(ItemRef frameRef)



Is the given frame the frontmost frame on its page?







Name
Type
Default
Description





Return

int
 

0 : no

1 : Yes






frameRef

ItemRef
-

Valid frame reference

0 : current script frame







Version 3.1 R1723, 3. Feb. 2010





priint:comet InDesign® Plug-Ins, comet_pdf





comet.CPageItem.isInFront








static   int is_at_back(ItemRef frameRef)



Is the given frame the last frame on its page?







Name
Type
Default
Description





Return

int
 

0 : no

1 : Yes






frameRef

ItemRef
-

Valid frame reference

0 : current script frame







Version 3.1 R1723, 3. Feb. 2010





priint:comet InDesign® Plug-Ins, comet_pdf





comet.CPageItem.isInBack








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



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







Name
Type
Default
Description





Return

int
 

0 :not overridden, not a parent page frame, error

1 : Yes, the parent page item is overridden on the given page






masterItem

ItemRef
-

Valid parent page item






pgNum

int
-

1-based page index in document






pageItem

ItemRef
0

On overridden parent page items, the variable contains the according page item.
May be 0, but if given, it must be allocated carefully (item::alloc).









Get the parent page items of the first document page and override the first frame. After this check both directions
(from the parent page and from the document page) - all results must be equal of course.



int main ()
{
    ItemList		masters		= itemlist::masteritems (0, "", 1, 0);
    ItemRef			masterItem	= item::alloc ();
    ItemRef			pageItem	= item::alloc ();
    int				result;

    itemlist::get (masters, masterItem, 0);

    result = frame::override_masteritem (masterItem, 3, pageItem);
    wlog ("", "# Action		Result	Parentitem	PageItem\n");
    wlog ("", "#    Override		%d	%d	%d\n", result, item::getint (masterItem), item::getint (pageItem));

    result = frame::is_masteritem_overriden (masterItem, 3, pageItem);
    wlog ("", "#    IsParentOverriden	%d	%d	%d\n", result, item::getint (masterItem), item::getint (pageItem));

    result = frame::is_overriden_masteritem (pageItem, masterItem);
    wlog ("", "#    IsOverridenParent	%d	%d	%d\n", result, item::getint (masterItem), item::getint (pageItem));
    wlog ("", "\n");

    return 0;
}


Version 2.1, R1760, 22.2.2010





priint:comet InDesign® Plug-Ins, comet_pdf







itemlist::masteritems
is_overriden_masteritem
override_masteritem
remove_masteritem_override

comet.CPageItem.isMasteritemOverriden








static   int is_overriden_masteritem(ItemRef pageItem, ItemRef masterItem = 0)



Give a page item, check whether it is an overridden parent page item.







Name
Type
Default
Description





Return

int
 

0 : not overridden, not coming from a parent page, error

1 : Yes, it is a overridden parent page item






pageItem

ItemRef
-

valid page item






masterItem

ItemRef
0

On overridden parent page items, the variable contains the according parent page item.
May be 0, but if given, it must be allocated carefully (item::alloc).









Get the parent page items of the first document page and override the first frame. After this check both directions
(from the parent page and from the document page) - all results must be equal of course.



int main ()
{
    ItemList		masters		= itemlist::masteritems (0, "", 1, 0);
    ItemRef			masterItem	= item::alloc ();
    ItemRef			pageItem	= item::alloc ();
    int				result;

    itemlist::get (masters, masterItem, 0);

    result = frame::override_masteritem (masterItem, 3, pageItem);
    wlog ("", "# Action		Res	Parent	PageItem\n");
    wlog ("", "#    Override		%d	%d	%d\n", result, item::getint (masterItem), item::getint (pageItem));

    result = frame::is_masteritem_overriden (masterItem, 3, pageItem);
    wlog ("", "#    IsParentOverriden	%d	%d	%d\n", result, item::getint (masterItem), item::getint (pageItem));

    result = frame::is_overriden_masteritem (pageItem, masterItem);
    wlog ("", "#    IsOverridenParent	%d	%d	%d\n", result, item::getint (masterItem), item::getint (pageItem));
    wlog ("", "\n");

    return 0;
}


Version 2.1, R1760, 22.2.2010





priint:comet InDesign® Plug-Ins, comet_pdf







itemlist::masteritems
is_masteritem_overriden
override_masteritem
remove_masteritem_override

comet.CPageItem.isOverridenMasteritem








static   int override_masteritem(
 	ItemRef masterItem,
 	int pgNum,
 	ItemRef newItem)



Override a given parent page item for a document page.




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







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






masterItem

ItemRef
-

Valid parent page item






pgNum

int
-

1-based page index in document






pageItem

ItemRef
0

On successful return, the variable contains the corresponding page item.
May be 0, but if given, it must be allocated properly (item::alloc).









Get the parent page items of the first document page and override the first frame. After this check both directions
(from the parent page and from the document page) - all results must be equal of course.



int main ()
{
    ItemList	masters		= itemlist::masteritems (0, "", 1, 0);
    ItemRef		masterItem	= item::alloc ();
    ItemRef		pageItem	= item::alloc ();
    int			result;

    itemlist::get (masters, masterItem, 0);

    result = frame::override_masteritem (masterItem, 3, pageItem);
    wlog ("", "# Action			Result	ParentItem	PageItem\n");
    wlog ("", "# Override		%d	%d	%d\n", result, item::getint (masterItem), item::getint (pageItem));

    result = frame::is_masteritem_overriden (masterItem, 3, pageItem);
    wlog ("", "# ParentOverriden	%d	%d	%d\n", result, item::getint (masterItem), item::getint (pageItem));

    result = frame::is_overriden_masteritem (pageItem, masterItem);
    wlog ("", "# OverridenParent	%d	%d	%d\n", result, item::getint (masterItem), item::getint (pageItem));
    wlog ("", "\n");

    return 0;
}


Version 2.1, R1760, 22.2.2010





priint:comet InDesign® Plug-Ins, comet_pdf







itemlist::masteritems
is_masteritem_overriden
is_overriden_masteritem
remove_masteritem_override

comet.CPageItem.overrideMasteritem








static   int remove_masteritem_override(ItemRef & pageItem)



Remove all overrides from a given frame. The function checks, if the given frame is an overridden parent page items and - if so -
removes all local changes. If the given frame pageItem is a member of an InDesign® group, the whole group is resetted.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






masterItem

ItemRef
-

Valid page item









Actually, the 'if'  is not necessary in the following script.



int main ()
{
    int				result;

    if (frame::is_overriden_masteritem (gFrame))
    {
        wlog ("", "# overridden parent item selected, removing overrides\n");
        result = frame::remove_masteritem_override (gFrame);
        wlog ("", "# 	result %d\n", result);
    }
    return 0;
}



Version 2.1, R1760, 22.2.2010





priint:comet InDesign® Plug-Ins, comet_pdf







itemlist::masteritems
is_masteritem_overriden
is_overriden_masteritem
override_masteritem

comet.CPageItem.removeMasteritemOverride








static   int copy_image(
 	ItemRef source,
 	ItemRef dest,
 	int applyLayoutRules = 0)



Copy an image into another frame. If the destination is not a Graphic Frame, it will converted. The image is duplicated using the same
position, size, rotation and skew. All effects are rebuilded. Optionally you can apply the  After geometry changes to fix the image
according to the given rules.








Name
Type
Default
Description





Return

int
 

0 oder Fehlercode






source

ItemRef
-

Gültige Rahmenreferenz






dest

ItemRef
-

Zielrahmen






applyLayoutRules

int
1

Apply layout rules  After geometry changes?


1 : Yes

0 : No










int main ()
{
    ItemRef		r1	= item::alloc ();
    ItemRef		r2	= item::alloc ();

    item::define (r1, document::current (), 206);
    item::define (r2, document::current (), 318);

    frame::copy_image (r1, r2, 1);

    return 0;
}


Version 3.2 R2127, 14. Sept. 2010





priint:comet InDesign® Plug-Ins













static   float get_visible_area(ItemRef frameRef, int flags = 0)



Calculate the size of visible part(s) of a frame. You may use the current clipping path for images instead of the frames shape. Shapaes and clipping paths may as complex as you want. even Bézier curves are
supported. The visble area of a frame is the intersection of the following areas :





As you can imagine easily, the procedure for calculating intersections and sizes of  arbitrary shapes is very complex. To solve the integrals of the curve pieces (Bézier curves),
some interpolations are used. This may cause an average error of 0.03 per thousand (150 times less than the allowed alcohol in alcohol-free beer).







Name
Type
Default
Description





Return

float
 

size of visible parts or 0.






frameRef

ItemRef
-

valid frame reference






flags

int
0

Control the calculation


kUseClippath : In case of images, use the intersection of the current image clip path and the frame shape instead of the frame shape alone.
Paths may be arbitrarily complex.


kAllowHoles : Normaly holes in images are counted to the image size. You may turn off this behavior by using the kAllowHoles flag.
The option is valid only if kUseClippath is active.


kCheckTransparenz : As described above, frame transparency is ignored for overlappings. Using image clip path stands in contradiction
to this assumption because the whole background is treated as transparent area. Using kCheckTransparenz, the clip path is used only if the frame has

    

  • no background color

  • blend mode is not "normal"

  • Oopacity is less than 100.0


The option is valid only if kUseClippath is active.


kIgnoreOverlaps : Ignore frames overlaping *frameRef*.
kUseMargins : Only visible parts of the frame are counted. Frame parts in the paste board are ignored.
If the flag kUseMargins is set, the visible background area is shrinked to page  of the frame without the page margins.





  #include "internal/types.h"




The example shows a layout rule fired on every geometry change. In this case, the areas of all page frames are recalculated. 



#include "internal/types.h"

int			gFlags	= kUseClippath+kUseMargins;

int recalc_area (ItemRef fr)
{
    float		A	= frame::get_visible_area (fr, flags);
    char		str	[5000];

    sprintf (str, "Visible :%f pt2\n", A);
    frame::replace (fr, str);
    wlog ("", "%d : %f square points\n", item::getint (fr), A);

    return 0;
}
int main ()
{
    ItemList	inter	= itemlist::pageframes (page::get (gFrame));
    ItemRef		f		= item::alloc ();
    int			i;

    for (i = 0; i < itemlist::length (inter); i++)
    {
        itemlist::get (inter, f, i);
        recalc_area (f);
    }

    return 0;
}



Version 3.2 R2210, 2. Dez. 2010





priint:comet InDesign® Plug-Ins







get_fill_level
document::get_visible_areas








static   float get_fill_level(
 	ItemRef frameRef,
 	int flags = 0,
 	float*  fa = 0,
 	float*  fi = 0,
 	float*  fv = 0,
 	float*  fh = 0)



Calculate the size of the shape and (if available) the image of a given frame. In addition you can calculate the size of the visible and hidden image parts.
The function returns the fill level of the frame in percent (0.0 - 100.0).







Name
Type
Default
Description





Return

float
 

fill level (0.0 - 100.0) of image frame


-1.0 : on

    

  • text frames

  • empty Graphic Frames

  • kCheckTransparenz an "non transparent" frame background, see parameter flags.

  • error


Except on the errors case, the shape size is calculated for every frame.






frameRef

ItemRef
-

valid frame reference






flags

int
0

Control the calculation


kAllowHoles : Normaly holes in images are counted to the image size. You may turn off this behavior by using the kAllowHoles flag.


kCheckTransparenz : As described above, frame transparency is ignored for overlappings. Using image clip path stands in contradiction
to this assumption because the whole background is treated as transparent area. Using kCheckTransparenz, the clip path is used only if the frame has

    

  • no background color

  • blend mode is not "normal"

  • Oopacity is less than 100.0








fa

float*
0

shape size given in square points






fi

float*
0

image size given in square points


0.0 on text or empty Graphic Frames






fv

float*
0

size of visible image parts in square points


0.0 on text or empty Graphic Frames






fh

float*
0

size of hidden image parts in square points


0.0 on text or empty Graphic Frames





  #include "internal/types.h"





#include "internal/types.h"

int main ()
{
    int			flags	= kAllowHoles + kCheckTransparenz;
    float		fa, fi, fv, fh;
    float		level	= frame::get_fill_level (gFrame, flags, &fa, &fi, &fv, &fh);

    wlog ("", "# Fill level of %d	: %f\n", item::getint (gFrame), level);
    wlog ("", "#     Shape	: %f\n", fa);
    wlog ("", "#     Image	: %f\n", fi);
    wlog ("", "#     Visible	: %f\n", fv);
    wlog ("", "#     Hidden	: %f\n", fh);
    wlog ("", "#     Free	: %f\n", fa-fv);

    return 0;
}



Version 3.2 R2210, 2. Dez. 2010





priint:comet InDesign® Plug-Ins







get_visible_area








static   int hide(ItemRef frameRef)



Hide a frame. The frame still exists in the document but isn't visible anymore.
You need at least CS5 for this feature. In versions prior CS5 the function will return an error code.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Valid page item


0 : current script frame









Hide all Comet group siblings of a frame.



int main ()
{
    int 		groupID	= frame::get_cometgroup (gFrame, 0);
    ItemList	group	= 0;
    ItemRef		mb		= item::alloc ();
    int 		i;

    if (groupID == 0)	return 0;
    group = itemlist::get_cometgroup_members (0, groupID, 1);
    if (!group)			return 0;

    for (i = 0; i < itemlist::length (group); i++)
    {
        mb			= itemlist::get (group, mb, i);

        if (item::getint (gFrame) != item::getint (mb))
        {
            frame::hide (mb);
        }
    }
}


CS5 Version 3.2 R2223, 14. Dez. 2010





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







show
is_hidden

comet.CPageItem.setVisible








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



Change the visibility state of a frame. You do not need to call this function after frame creations by frame::create, <in>-tag, inserting templates, and so on.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Valid page item


0 : current script frame






visibility

int
1

new visibility


0 : hidden

1 : visible







CS5 Version 3.2 R2223, 14. Dez. 2010





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







hide
is_hidden

comet.CPageItem.setVisible







static   int is_hidden(ItemRef frameRef)



Get the curren visibility of a frame.







Name
Type
Default
Description





Return

int
 

1 : visible

0 : hidden or error code






frameRef

ItemRef
-

Valid page item


0 : current script frame







CS5 Version 3.2 R2223, 14. Dez. 2010





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







show
hide

comet.CPageItem.getVisible







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



Get a frame's name. Names are displayed inside the layer panel.




To change the name, select the desired frame in the Layers panel.
After a short moment, click the selected entry again.
Make sure that the time between the two clicks is longer than a double-click!
Shortly after the second click, the frame name changes to an editable field and you can now specify your own name.
Custom names should not start with a #!








Name
Type
Default
Description





Return

char*
 

Name of frame.

The return value is read only, do NOT CHANGE.
The result will be overridden on following calls to the function.
See here to learn more about functions returning r/o char* values.







frameRef

ItemRef
-

Valid page item


0 : current script frame






nameType

int
0

What kind of name you wish to retrieve?


0 : user defined name. If empty, default name.

1 : default name

2 : user defined name. If not set, the result string is empty ("")






doTranslate

int
0

Translate the default name? The internal untranslated name of an empty Graphic Frame is  #Graphicframe. This is translated to Graphic Frame by an English
version of InDesign®.


0 : do not translate

1 : translate









Set the names of all frames of a Comet group



int main ()
{
    int 		groupID	= frame::get_cometgroup (gFrame, 0);
    ItemList	group	= 0;
    ItemRef		mb		= item::alloc ();
    int 		i;
    char		name[2000];
    if (groupID == 0)	return 0;
    group = itemlist::get_cometgroup_members (0, groupID, 1);
    if (!group)			return 0;

    for (i = 0; i < itemlist::length (group); i++)
    {
        mb			= itemlist::get (group, mb, i);

        wlog ("", "# Frame %d :\n", item::getint (mb));
        wlog ("", "#	'%s'\n", frame::get_name (mb));

        sprintf (name, "Cometgroup %d.%d", groupID, i+1);
        frame::set_name (mb, name);

        wlog ("", "#	'%s'\n", frame::get_name (mb));
    }
}


CS5 Version 3.2 R2223, 14. Dez. 2010





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







set_name
itemlist::pageframes

comet.CPageItem.getName








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



Set a frame's name. Names are displayed inside the layer panel.




To change the name, select the desired frame in the Layers panel.
After a short moment, click the selected entry again.
Make sure that the time between the two clicks is longer than a double-click!
Shortly after the second click, the frame name changes to an editable field and you can now specify your own name.
Custom names should not start with a #!







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Valid page item


0 : current script frame






newName

String or char*
0

New name of frame


0 or "" : Reset name to InDesign® default.









Set the names of all frames of a Comet group



int main ()
{
    int 		groupID	= frame::get_cometgroup (gFrame, 0);
    ItemList	group	= 0;
    ItemRef		mb		= item::alloc ();
    int 		i;
    char		name[2000];
    if (groupID == 0)	return 0;
    group = itemlist::get_cometgroup_members (0, groupID, 1);
    if (!group)			return 0;

    for (i = 0; i < itemlist::length (group); i++)
    {
        mb			= itemlist::get (group, mb, i);

        wlog ("", "# Frame %d :\n", item::getint (mb));
        wlog ("", "#	'%s'\n", frame::get_name (mb));

        sprintf (name, "Cometgroup %d.%d", groupID, i+1);
        frame::set_name (mb, name);

        wlog ("", "#	'%s'\n", frame::get_name (mb));
    }
}


CS5 Version 3.2 R2223, 14. Dez. 2010





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







get_name
itemlist::pageframes
comet.CPageItem.setName








static   int get_page_element(
 	ItemRef frameRef = 0,
 	int chkGroup = 0,
 	int checkLeftTopOnly = 0,
 	char*  out_element_name = 0,
 	int queryNearest = 0)



Find the page element of a given frame or its Comet group.







Name
Type
Default
Description





Return

int
 

1-based sequence number of the page element or -1 in case of some errors






frameRef

ItemRef
0

valid frame reference


0 : current script frame






chkGroup

int
0

0 : use frame only


1 : use Comet group of frame






checkLeftTopOnly

int
0

0 : The whole bounding box of the frame (or its Comet group) must match the page element


1 : The top left corner of bounding box of the frame (or its Comet group) must be inside the page element






out_element_name

String or char*
0

Allocated string for the name of the found page element


0 : ignore name






queryNearest

int
0

Behavior on overlapping elements


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


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


The parameter is used only if  checkLeftTopOnly == 1.









Get the page element of a frame by checking its top left corner.



int main ()
{
    char		ename [2000];
    int			seq;

    seq	= frame::get_page_element (gFrame, 0, 1, ename);

    wlog ("", "# Frame %d\n", item::getint (gFrame));
    wlog ("", "#	Element	: %d (%s)\n", seq, ename);

    return 0;
}


Version 3.2 R2267, 8. Feb. 2011

queryNearest since v4.0.5 R20456, 10. Oct. 2017





priint:comet InDesign® Plug-Ins, comet_pdf







productlist::get_established
get_template
get_chapter_id
get_smart_item_data
datapool::get_main_template
datapool::get_template_name

comet.CFrame.getPageElement








static   int get_template(ItemRef frameRef = 0, char*  out_template_name = 0)



Find the template that inserted a frame into the document.







Name
Type
Default
Description





Return

int
 

template ID or 0 in case of some errors






frameRef

ItemRef
0

valid frame reference


0 : current script frame






out_element_name

String or char*
0

Allocated string for the name of the found template


0 : ignore name










int main ()
{
    char		ename [2000];
    int			tid;
    int			ttid, l, m, r, cl, cm, cr;

    tid	= frame::get_template (gFrame);
    ttid	= datapool::get_main_template (tid, &l, &m, &r, &cl, &cm, &cr);

    wlog ("", "# Frame %d\n", item::getint (gFrame));
    wlog ("", "#	Template	: %d of %d (%s) with [%d, %d, %d, %d, %d, %d]\n",
    tid, ttid,
    datapool::get_template_name (tid),
    l, m, r, cl, cm, cr);

    return 0;
}


Version 3.2 R2267, 8. Feb. 2011





priint:comet InDesign® Plug-Ins, comet_pdf







productlist::get_established
get_page_element
get_chapter_id
get_smart_item_data
datapool::get_main_template
datapool::get_template_name

comet.CFrame.getTemplate








static   int get_chapter_id(ItemRef frameRef = 0)



Find the chapter id of a frame. Chapter IDs are defined to support page breaks while establishing products.







Name
Type
Default
Description





Return

int
 

template ID or 0 in case of some errors






frameRef

ItemRef
0

valid frame reference


0 : current script frame







Version 3.2 R2267, 8. Feb. 2011





priint:comet InDesign® Plug-Ins, comet_pdf





productlist::get_established
get_page_element
get_template
get_smart_item_data
datapool::get_main_template
datapool::get_template_name








static   int get_smart_item_data(
 	ItemRef frameRef = 0,
 	char*  label = 0,
 	int*  seq = 0,
 	int*  type = 0,
 	int* prerule = 0,
 	int*  forTextflow = 0,
 	int*  forBuild = 0,
 	int*  flags = 0,
 	int*  nettoAreaType = 0)



Get the frame properties to support products buildings. Set this properties using the panel 'Template behavior'.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
0

valid frame reference


0 : current script frame






label

String or char*
0

frame label






seq

int*
0

sequence number






type

int*
0

Type


0 : normal

1 : can continue

2 : repeat (not supported for now)

3 : can continue but do not change its height







prerule

int*
0

rule to execute before inserting template


-3 :new right page

-2 : new left page

-1 : new page






forTextflow

int*
0

Use this frame in text flows?


0 : insert text content

1 : insert as inline

2 : do not use






forBuild

int*
0

Use for builds?


0 : yes

1 : do not use

2 : use but ignore on reorganizations






flags

int*
0

Bit field with additional infos


0x00000001 : Load frame placeholder

0x00000002 : Load text placeholder






nettoAreaType

int*
0

Area type


0 : Bounding Box

1 : Path (star)

2 : Path with holes (empty star)

3 : ignore (minus)











int main ()
{
    char			label [128];
    int 			seq, type, prerule, text, build;

    strcpy (label, "");
    frame::get_smart_item_data (gFrame, label, &seq, &type, &prerule, &text, &build);
    wlog ("", "# Frame %d\n", item::getint (gFrame));
    wlog ("", "#	Label	: '%s'\n", label);
    wlog ("", "#	Seq	: %d\n", seq);
    wlog ("", "#	Type	: %d\n", type);
    wlog ("", "#	Pre	: %d\n", prerule);
    wlog ("", "#	Text	: %d\n", text);
    wlog ("", "#	Build	: %d\n", build);

    return 0;
}


Version 3.2 R2267, 8. Feb. 2011

Parameter flags und nettoAreaType since v3.3 R3237, 25.10.2012





priint:comet InDesign® Plug-Ins, comet_pdf







productlist::get_established
get_page_element
get_template
get_chapter_id
datapool::get_main_template
datapool::get_template_name
placeholder::sget_value
placeholder::change_tags

comet.CFrame.getSmartItemData








static   int set_smart_item_data(
 	ItemRef frameRef = 0,
 	char*  label = 0,
 	int seq = -1,
 	int type = -1,
 	int prerule = -1,
 	int forTextflow = -1,
 	int forBuild = -1,
 	int flags = -1,
 	int nettoAreaType = -1)



Set the frame properties to support products buildings. Be extremely careful while changing this values!







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
0

valid frame reference


0 : current script frame






label

String or char*
0

New frame label. Only the first character of the string is used.


0 : do not change






seq

int
-1

sequence number


-1 : do not change






type

int
-1

Type


-1 : do not change

0 : normal

1 : can continue

2 : repeat (not supported for now)

3 : can continue but do not change its height







prerule

int
-4

rule to execute before inserting template


-4 : do not change

-3 :new right page

-2 : new left page

-1 : new page






forTextflow

int
-1

Im Textfluss benutzt?


-1 : do not change

0 : insert text content

1 : insert as inline

2 : do not use






forBuild

int
-1

Use for builds?


-1 : do not change

0 : yes

1 : do not use

2 : use but ignore on reorganizations






flags

int
-1

Bit field with additional infos


-1 : do not change

0x00000001 : Load frame placeholder

0x00000002 : Load text placeholder






nettoAreaType

int
-1

Area type


-1 : do not change

0 : Bounding Box

1 : Path (star)

2 : Path with holes (empty star)

3 : ignore (minus)








v3.3 R3237, 25.10.2012





priint:comet InDesign® Plug-Ins, comet_pdf





frame::get_smart_item_data
placeholder::sget_value
placeholder::change_tags

comet.CFrame.setSmartItemData








static   int change_rule_param(int index, char*  str)



Change a parameter of a layout rule. The function has an effect only on layout rules. Parameter values must be not longer than 5000.




You may change gParam1, ..., gParam4 directly inside a layout rule. But this changes are not taken to the document.
Subsequent calls to the rule will use the unchanged old parameters. Using change_rule_param you change the parameter directly inside the document.



Attention : change_rule_param will also change your local copie of the parameter value gParam1, ..., resp. gParam4.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






index

int
-

1-4 for the appropriate parameter






str

String or char*
-

New value. Attention : change_rule_param will also change your local copy of the parameter value gParam1, ..., resp. gParam4.









Everytime the rule is executed, parameter 2 is increased by 1. Parameter 2 must be intiated by an integer.



int main ()
{
    frame::change_rule_param (2, itoa (val (gParam2)+1));
    return 0;
}





Change the image placement on every call of the rule. Parameter 1 must be intiated by an integer in the range 1-9.



int main ()
{
    int 			alig	= val (gParam1);

    alig = alig + 1;
    if (alig > 9) alig = 1;

    frame::fit_image (gFrame, 5, alig, 195.0);

    wlog ("", "111 : %s\n", gParam1);
    frame::change_rule_param (1, itoa (alig));
    wlog ("", "222 : %s\n", gParam1);

    return 0;
}



Version 3.2.3 R2310, 26.04.2011





priint:comet InDesign® Plug-Ins













static   int shows_textend(ItemRef frameRef)



Does the frame contain the end of the text?







Name
Type
Default
Description





Return

int
 

1 : Error


0 : No (Frame has an overset or is linked together with another text frame.)


1 : Yes, text ends here.


2 : Frame does not contain text (This happens in a text frame chain with more frames than text.)






frameRef

ItemRef
0

Valid frame reference


0 : current script frame







Version 3.2.3 R2312, 29.04.2011





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





textmodel::overset

comet.CFrame.showsTextEnd








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


DEPRECATED! Please use the function interactive::get instead.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode







Please use the function interactive::get instead.









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


Deprecated! Please use the function interactive::get instead.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode







Please use the function interactive::get instead.









static   int set_area_build_parameter(
 	ItemRef frameRef,
 	int parameterType,
 	int value)



Set a layoutparameter for the area build mode.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Valid frame reference


0 : current frame






parameterType

int
-

Which layout parameter should be set?

    

  • 0: No
    • 

  • 1: Yes
    • 


	
Value Layout parameter which is being set Possible values for value Data type 



0
Build mode
Changing this parameter causes the other alignment parameters to reset to their default values.		


    

  • 0: Row by row
    • 

  • 1: Column by column
    • 



int




1
Horizontal direction


    

  • 0: Left to right
    • 

  • 1: Right to left
    • 







2
Vertical direction


    

  • 0: Top to bottom
    • 

  • 1: Bottom to top
    • 







3
Internal row/column alignment:
First row/column		


    

  • 0: Top/Left
    • 

  • 1: Centered
    • 

  • 2: Bottom/Right
    • 







4
Internal row/column alignment:
Intermediate rows/columns		


    

  • 0: Top/Left
    • 

  • 1: Centered
    • 

  • 2: Bottom/Right
    • 







5
Internal row/column alignment:
Last row/column		


    

  • 0: Top/Left
    • 

  • 1: Centered
    • 

  • 2: Bottom/Right
    • 







6
Row/Column alignment to frame
First row/column		


    

  • 0: Left/Top
    • 

  • 1: Centered
    • 

  • 2: Right/Bottom
    • 

  • 3: Justify Horizontally/Vertically
    • 







7
Row/Column alignment to frame
Intermediate rows/columns		


    

  • 0: Left/Top
    • 

  • 1: Centered
    • 

  • 2: Right/Bottom
    • 

  • 3: Justify Horizontally/Vertically
    • 







8
Row/Column alignment to frame
Last row/column																		

    

  • 0: Left/Top
    • 

  • 1: Centered
    • 

  • 2: Right/Bottom
    • 

  • 3: Justify Horizontally/Vertically
    • 







9
Row/Column distribution in frame


    

  • 0: Top/Left
    • 

  • 1: Centered
    • 

  • 2: Bottom/Right
    • 

  • 3: Justify Vertically/Horiontally
    • 







10
X Minimum distance

float




11
Y Minimum distance




12
Make invisible

int










value

int/float
-

New value - the data type of this parameter is dependend on the parameter type(see table parameterType above).







Version 4.1 R14700





priint:comet InDesign® Plug-Ins, comet_pdf





Documentation for area building

frame::get_area_build_parameter








static   int get_area_build_parameter(ItemRef frameRef, int parameterType)



Get a layoutparameter for the area build mode.







Name
Type
Default
Description





Return

int/float
 

Value of the queried parameter. Data type depends on the queried parameter (See table at frame::set_area_build_parameter).






frameRef

ItemRef
-

Valid frame reference


0 : current frame






parameterType

int
-

Which layout parameter should be gotten? See table at frame::set_area_build_parameter









Get the area build mode of the current frame (Row/Column) 



int main()
{
    int 	mode = -1;

    mode = frame::get_area_build_parameter(gFrame, 0);
    if (mode == 0)
    {
        showmessage("Frame is in row build mode");
    }
    else if (mode == 1)
    {
        showmessage("Frame is in column build mode");
    }
    else
    {
        showmessage("Failed to get mode from frame");
    }

    return 0;
}





Get the X minimum distance of the current frame (float-value)	



int main()
{
    float xDistance = -1.0;

    xDistance = frame::get_area_build_parameter(gFrame, 10);
    if (xDistance >= 0.0)
    {
        showmessage("Frame has minimum x distance of %.2fpt set", xDistance);
    }

    return 0;
}


Version 4.1 R14700





priint:comet InDesign® Plug-Ins, comet_pdf







Documentation for area building

frame::set_area_build_parameter








static   int is_area_build_masterframe(ItemRef frameRef)



Determines wether the frame is the first element of an area build frame chain.







Name
Type
Default
Description





Return

int
 

0 (No) or 1 (Yes)






frameRef

ItemRef
-

Valid frame reference


0 : current frame







Version 4.1 R14700





priint:comet InDesign® Plug-Ins, comet_pdf





Documentation for area building








static   int add_to_area_build_chain(ItemRef frameOfExistingChain, ItemRef frameRef)



Adds a frame to an area build frame chain.







Name
Type
Default
Description





Return

int
 

0 oder Fehlercode






frameOfExistingChain

ItemRef
-

Frame of an existing area build frame chain or frame with area build placeholder






frameRef

ItemRef
-

Valid frame reference


0 : current frame







Version 4.1 R14700





priint:comet InDesign® Plug-Ins, comet_pdf





Documentation for area building








static   int remove_from_area_build_chain(ItemRef frameRef)



Removes a frame from an area build chain.







Name
Type
Default
Description





Return

int
 

0 oder Fehlercode






frameRef

ItemRef
-

Valid frame reference


0 : current frame







Version 4.1 R14700





priint:comet InDesign® Plug-Ins, comet_pdf





Documentation for area building








static   int get_area_build_order(ItemRef frameRef)



Get the order of a frame inside an area build frame chain. The result is a multiple of ten or -1 (Frame does not belong to a frame chain).







Name
Type
Default
Description





Return

int
 

Order number inside the frame chain (-1 = Frame does not belong to a chain. 0 = Frame is parent frame of the chain).






frameRef

ItemRef
-

Valid frame reference


0 : current frame







Version 4.1 R14700





priint:comet InDesign® Plug-Ins, comet_pdf





Documentation for area building








static   int move_in_area_build_order(ItemRef frameRef, int moveUp)



Moves a frame inside the order of an area build frame chain. Does not work on the first frame of the chain or when moving a frame inside the order is not possible (e.g. Moving the last frame in the chain downwards).







Name
Type
Default
Description





Return

int
 

0 oder Fehlercode






frameRef

ItemRef
-

Valid frame reference


0 : current frame






moveUp

int
-

Move frame up or down? 


0: Down 

1: Up







Version 4.1 R14700





priint:comet InDesign® Plug-Ins, comet_pdf





Documentation for area building








static   int get_area_build_chain_members(ItemRef frameRef, ItemList memberList)



Moves a frame inside the order of an area build frame chain. Does not work on the first frame of the chain or when moving a frame inside the order is not possible (e.g. Moving the last frame in the chain downwards).







Name
Type
Default
Description





Return

int
 

0 oder Fehlercode






frameRef

ItemRef
-

Valid frame reference


0 : current frame






memberList

ItemList
-

A list allocated with itemlist::alloc for the results. When the list remains empty the frame does not belong to a frame chain.







Version 4.1 R14700





priint:comet InDesign® Plug-Ins, comet_pdf





Documentation for area building








static   int reorganize_area_build_frames(ItemRef frameRef)



Reorganizes the already built repeating elements in an area build chain.
Elements which no longer fit into the layout frames are deleted from the document.







Name
Type
Default
Description





Return

int
 

0 oder Fehlercode






frameRef

ItemRef
-

First layout frame of an area build chain.


0 : current frame







Version 4.1 15678





priint:comet InDesign® Plug-Ins, comet_pdf





Documentation for area building








static   int get_area_build_placed_into(ItemRef frameRef)



Get the layout frame in which an element frame was placed during an area build process.
The result can be ascertained using two methods:


Build information: Get the layout frame which the element frame was placed into during area build


Geometry: Get the first layout frame of the layout frame chain which completely contains this element frame.







Name
Type
Default
Description





Return

int
 

ErrorCode or 0






resultFrame

ItemRef
-

Reserved memory for the result.






inputFrame

ItemRef
-

Frame of the element.






mode

int
0

Mode


0: Build information

1: Geometry







Version 4.1 21612





priint:comet InDesign® Plug-Ins, comet_pdf





Documentation for area building








static   int get_printable(ItemRef frameRef = 0)



Printability* of frames.



*) "Printability" means printing and PFD exports.







Name
Type
Default
Description





Return

int
 

Frame printable?

1 : yes

0 : no







frameRef

ItemRef
0

Valid frame


0 : current frame







v3.3 R2800, 21. Feb. 2012





priint:comet InDesign® Plug-Ins







document::get_notes_printable
document::set_notes_printable

comet.CPageItem.getPrintable







static   int set_printable(ItemRef frameRef = 0, int newState = 0)



Set the printability* of a frame.



*) "Printability" means printing and PFD exports.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
0

valid frame reference


0 : current frame






newState

int
0

Printability

0 : Do not print or export to PDF

1 : Print and export to PDF









Toggle the print state of a frame.



int main ()
{
    frame::set_printable (gFrame, !frame::get_printable (gFrame));
    return 0;
}


v3.3 R2800, 21. Feb. 2012





priint:comet InDesign® Plug-Ins







document::get_notes_printable
document::set_notes_printable
comet.CPageItem.setPrintable








static   int set_alt(
 	ItemRef fr,
 	int source,
 	char*  altText)



Define an alternative text description for a frame.
Manually this setting can be changed in InDesign®
dialog Object -> Object Export Options...
in the category Alt Text.







Name
Type
Default
Description





Return

int
 

0 or Error Code






fr

ItemRef
-

Valid frame reference


0 : Current script frame






source

int
0

Alt Text Source



0 : Custom. The text is specified in the parameter altText.


Attention : Even if you explicitly specify a text for the PDF Accessibilty Structure (Tagged PDF)
using frame::set_pdf_accessibility,
the Adobe Acrobat read-aloud function will use the alternative text specified here
(and not the text specified for the PDF Accessibility Structure).


8 : Decorative image (no Alt Text)



The texts for the following information are determined from the IPTC core of the XMP structure of the image.
You can (for instance) define this information using the Metadata palette of Adobe Bridge.

1 : From XMP:Title

2 : From XMP:Description

3 : From XMP:Headline

6 : From XMP:Alt Text (Accessibility)

7 : From XMP:Extended Description (Accessibility)



The values are set but not further supported by priint:comet.

4 : From other XMP

5 : From Struktur






altText

char* oder String
0

User-defined alternative (custom) text.
The specification is used only for source 0 (custom).







v5.0 R35020





priint:comet InDesign® Plug-Ins







get_alt
set_pdf_accessibility
get_pdf_accessibility

comet.CPageItem.setAlternativeText







static   int get_alt(
 	ItemRef fr,
 	int*  source,
 	char* altText,
 	char* nsPrefix,
 	char*  propertyPath)



Determine the settings for the alternative text of a frame.
Manually this setting can be changed in InDesign®
dialog Object -> Object Export Options...
in the category Alt Text.







Name
Type
Default
Description





Return

int
 

0 or Error Code






fr

ItemRef
-

Valid frame reference


0 : Current script frame






source

int*
0

Variable for the determined source of alternative text.
A description of the values can be found in frame::set_alt.


0 : Wert ignorieren







altText

char* or String
0

Variable for the user-defined alternative text.
It is irrelevant whether the frame actually uses this custom text (type 0) or not.


0 :  Ignore value

Otherwise : String or char*|[..] variable. In the case of char*|[..], the variable must be allocated large enough to hold the result!






nsPrefix

char* or String
0

Variable for the namespace prefix in the XMP header.
For XMP-based texts this value is defined automatically and is only of technical interest here.



0 :  Ignore value

Otherwise : String or char*|[..] variable. In the case of char*|[..], the variable must be allocated large enough to hold the result!






propertyPath

char* or String
0

Variable for the property path in the XMP header.
For XMP-based texts this value is defined automatically and is only of technical interest here



0 :  Ignore value

Otherwise : String or char*|[..] variable. In the case of char*|[..], the variable must be allocated large enough to hold the result!







v5.0 R35020





priint:comet InDesign® Plug-Ins







set_alt
set_pdf_accessibility
get_pdf_accessibility

comet.CPageItem.getAlternativeText







static   int set_pdf_accessibility(
 	ItemRef fr,
 	int type,
 	int source,
 	char*  text)



Define an accessible description text for a frame.
Manually this setting can be changed in InDesign®
dialog Object -> Object Export Options...
in the category Tagged PDF.







Name
Type
Default
Description





Return

int
 

0 or Error Code






fr

ItemRef
-

Valid frame reference


0 : Current script frame






type

int
0

Apply Tag:


0 : From structure

1 : Artifact

2 : Based On Object






source

int
0

Actual Text Source



0 : Custom. The text is specified in the parameter altText.



The texts for the following information are determined from the IPTC core of the XMP structure of the image.
You can (for instance) define this information using the Metadata palette of Adobe Bridge.

1 : From XMP:Title

2 : From XMP:Description

3 : From XMP:Headline

6 : From XMP:Alt Text (Accessibility)

7 : From XMP:Extended Description (Accessibility)



The values are set but not further supported by priint:comet.

4 : From other XMP

5 : From Struktur






text

char* oder String
0

User-defined (custom) accessible description text
The specification is used only for source 0 (custom).







v5.0 R35020





priint:comet InDesign® Plug-Ins







get_pdf_accessibility
set_alt
get_alt

comet.CPageItem.setPDFAccessibility







static   int get_pdf_accessibility(
 	ItemRef fr,
 	int*  type,
 	int*  source,
 	char* text,
 	char* nsPrefix,
 	char*  propertyPath)



Determine the settings for the accessible description text of a frame.
Manually this setting can be changed in InDesign®
dialog Object -> Object Export Options...
in the category Alt Text.







Name
Type
Default
Description





Return

int
 

0 or Error Code






fr

ItemRef
-

Valid frame reference


0 : Current script frame






type

int*
0

Variable for the determined type of the source of the accessible description text.
A description of the values can be found in frame::set_pdf_accessibility.


0 : Ignore value







source

int*
0

Variable for the determined source of the accessible description text.
A description of the values can be found in frame::set_pdf_accessibility.


0 : Ignore value







text

char* or String
0

Variable for the user-defined accessible description text.
It is irrelevant whether the frame actually uses this custom text (type 0) or not.


0 :  Ignore value

Otherwise : String or char*|[..] variable. In the case of char*|[..], the variable must be allocated large enough to hold the result!






nsPrefix

char* or String
0

Variable for the namespace prefix in the XMP header.
For XMP-based texts this value is defined automatically and is only of technical interest here.



0 :  Ignore value

Otherwise : String or char*|[..] variable. In the case of char*|[..], the variable must be allocated large enough to hold the result!






propertyPath

char* or String
0

Variable for the property path in the XMP header.
For XMP-based texts this value is defined automatically and is only of technical interest here



0 :  Ignore value

Otherwise : String or char*|[..] variable. In the case of char*|[..], the variable must be allocated large enough to hold the result!







v5.0 R35020





priint:comet InDesign® Plug-Ins







set_pdf_accessibility
set_alt
get_alt

comet.CPageItem.getPDFAccessibility







static   int store_magnet_distances(ItemRef frames)



Save magnet distances of a frame and all frames reachable from this frame.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frame

ItemRef
-

valid frame


0 : current script frame










int main ()
{
    frame::store_magnet_distances (0);
    return 0;
}


v3.3 R850, 29.03.2012





priint:comet InDesign® Plug-Ins







itemlist::store_magnet_distances








static   int set_corner(
 	ItemRef frameRef = 0,
 	int corner = 0,
 	int type = 0,
 	float radius = 0.0)



Set corner options of a frame.
To define the line ends (line cap) and how the lines joind (join type) please use the functions color, color_rgb or color_cmyk.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
0

valid frame


0 : current script frame






corner

int
0

Corner of interest


0 :alle corners


Following setting will work from CS5 only.


1 : left top

2 : right top

3 : left bottom

4 : right bottom






type

int
0

Corner type


0 : plain

1 : rounded

2 : inverse rounded

3 : inset

4 : bevel

5 : fancy






radius

float
0.0

Radius in points







v3.3 R3136, 29.08.2012





priint:comet InDesign® Plug-Ins, comet_pdf







get_corner







static   int get_corner(
 	ItemRef frameRef = 0,
 	int corner = 0,
 	int*  type = 0,
 	float*  radius = 0)



Get corner options of a frame.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
0

valid frame


0 : current script frame






corner

int
0

Corner of interest


0 : All corners. This only works if all corners having the same settings.

1 : left top

2 : right top

3 : left bottom

4 : right bottom






type

int*
0

After successful return it contains the type of the corner


0 : plain

1 : rounded

2 : inverse rounded

3 : inset

4 : bevel

5 : fancy






radius

float*
0.0

After successful return it contains the radius of the corner in points







v3.3 R3136, 29.08.2012





priint:comet InDesign® Plug-Ins, comet_pdf







set_corner







static   int apply_magnets(
 	ItemRef frame = 0,
 	int applyRules = 0,
 	int applyBuildActions = 1)



Apply magnets of a given frame. Recursive updating of all frames depending on the given frame.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
0

valid frame


0 : current script frame






applyRules

int
0

Apply adapter rules of frames?


0 : No

1 : Yes






applyBuildActions

int
1

Apply rules of type "While building products" of frames?


0 : No

1 : Yes







v3.3 R4100, 1. Aug. 2013





priint:comet InDesign® Plug-Ins, comet_pdf




Parameter applyRules and applyBuildActions since v4.0.5 R11000



get_nail
incoming_magnets
outgoing_magnets
get_magnet_type
get_magnet_reference

comet.CFrame.applyMagnets







static   int apply_magnet_rules(
 	ItemRef frame,
 	int actionType,
 	int actionIndex)



Apply adapter rules of a given frame.




The global variables gPage~Org, gPage~New, g~Resize~, gOrgFrame~,
gLastFrame~, gOrgImage~ defined in this scripts are depending on the current page size changes and may have invalid values here!







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
0

valid frame


0 : current script frame






actionType

int
-

Apply rules of the given type:


1 : Before adaption

2 : After move

3 : After resize

4 : After adaption

6 : While building products







actionIndex

int
-

Index of rule in frame


-1 : Apply all rules of the given type


otherwise : 0-based index of rule. Action type is ignored in this case. If the given rule is diabled, it is executed anyway. You may use this behavior,
to define rules execute only from this function but ignored by any adaption.







v4.0.5 R11000, 21. Apr 2016





priint:comet InDesign® Plug-Ins, comet_pdf











static   int rmv_magnets(ItemRef frame, int full_closure = 0)



Remove all nails, magnets and adapter script from all frames of a given list.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frame

ItemRef
-

Valid frame






full_closure

int
0

0 : Only edit this frame


Otherwise : Also edit all frames that are connected to this frame via magnets.







v3.4 R5356, 2. Jul 2014





priint:comet InDesign® Plug-Ins, comet_pdf







itemlist::rmv_magnets

comet.CFrame.removeMagnets








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





comet.CFrame.isNote








static   int write_frame_info(ItemRef document, ItemRef frame)



Write information about a frame into the data sources. This can overwrite existing frame info entries. More information at Frame infos







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






document

ItemRef
-

Document






frame

ItemRef
- 

Frame






frameSearchFlags

int
kUseDefault

How should frame infos to overwrite be identified?

Combination of the following flags: 

kUseDefault	(kUseTemplateId + kUseFrameLabel + kUseRecordStringId + kUseBuildByRecordStringId)

kUseTemplateId 

kUseFrameLabel 

kUseRecordStringId	

kUseBuildByRecordStringId	

kUsePlaceholderId	

kUseFrameType	

kUseScriptTags	

kUseRecordStringId	

kUseFrameUID	

kUsePlaceholderInfo1	

kUsePlaceholderInfo2	

kUseFrameInfoId Use the value of the scripttag "frameInfoId"

kUseRecordId	

kUseRecordId2	

kUseRecordId3	

kUseBuildByRecordId	

kUseBuildByRecordId2	

kUseBuildByRecordId3	







documentType

int
kLocalDoc

In which document scope should we search for existing frame infos?

kLocalDoc 







conflictBehavior

int
kThrowError

Behavior when multiple search results are found per frame 

kThrowError	Leaves the frame info entry unchanged and puts an error message into the logfile.

kUseLatest	Overwrites the frame with the most recent update date.






  #include "internal/frameinfos.h"





Write the current frame



int main ()
{
    return frame::write_frame_info(gDocument, gFrame);
}



v4.0.5





priint:comet InDesign® Plug-Ins, comet_pdf







frame::apply_frame_info








static   int apply_frame_info(
 	ItemRef document,
 	ItemRef frame,
 	int propertyFlags,
 	int searchType,
 	int documentType,
 	StringList keyValues = 0)



Restore saved information about a frame from the data sources and set it back to the frame. More information at Frame infos







Name
Type
Default
Description





Return

int
 

0 oder ErrorCode






document

ItemRef
-

Document






frame

ItemRef
- 

Frame






propertyFlags

int
-

Which information should be restored? 

Combination of the following flags:

kApplyScriptTags	

kApplyPage 

kApplyLayer 

kApplyXPosAbs 

kApplyYPosAbs 

kApplyXPosRel : Not possible when kApplyXPosAbs is set!

kApplyYPosRel : Not possible when kApplyYPosAbs is set!

kApplyWidth 

kApplyHeight 

kApplyFrameRotate 

kApplyFrameSkew 

kApplyImageXOffset : Only for Graphic Frames

kApplyImageYOffset : Only for Graphic Frames

kApplyImageXScale : Only for Graphic Frames

kApplyImageYScale : Only for Graphic Frames

kApplyImageRotate : Only for Graphic Frames

kApplyImageSkew : Only for Graphic Frames

kApplyObjectStyle 







frameSearchFlags

int
kUseDefault

How should the stored frame be identified?

Combination of the following keywords: 

kUseDefault	(kUseTemplateId + kUseFrameLabel + kUseRecordStringId + kUseBuildByRecordStringId)

kUseTemplateId 

kUseFrameLabel 

kUseRecordStringId	

kUseBuildByRecordStringId	

kUsePlaceholderId	

kUseFrameType	

kUseScriptTags	

kUseRecordStringId	

kUseFrameUID	

kUsePlaceholderInfo1	

kUsePlaceholderInfo2	

kUseFrameInfoId	Use the value of the scripttag "frameInfoId"

kUseRecordId	

kUseRecordId2	

kUseRecordId3	

kUseBuildByRecordId	

kUseBuildByRecordId2	

kUseBuildByRecordId3	







documentType

int
kLocalDoc

How should the document source be identified?

kLocalDoc 







conflictBehavior

int
kThrowError

Behavior when multiple search results are found per frame 

kThrowError	Leaves the frame unchanged and puts an error message into the logfile.

kUseLatest	Uses the frame info with the most recent update date.






  #include "internal/frameinfos.h"




Restore frame geometry of the current frame



#include "internal/frameinfos.h"

int main ()
{
    int 	propertyFlags = kApplyXPosAbs
     					+ kApplyYPosAbs
     					+ kApplyWidth
     					+ kApplyHeight
     					+ kApplyFrameRotate
     					+ kApplyFrameSkew;

    return frame::apply_frame_info(gDocument, gFrame, propertyFlags, kUseDefault, kLocalDoc);
}





Restore all properties of the current frame



#include "internal/frameinfos.h"

int main ()
{
    int 	propertyFlags = kApplyScriptTags
     					+ kApplyXPosAbs
     					+ kApplyYPosAbs
     					+ kApplyWidth
     					+ kApplyHeight
     					+ kApplyFrameRotate
     					+ kApplyFrameSkew
     					+ kApplyImageXOffset
     					+ kApplyImageYOffset
     					+ kApplyImageXScale
     					+ kApplyImageYScale
     					+ kApplyImageRotate
     					+ kApplyImageSkew;

    return frame::apply_frame_info(gDocument, gFrame, propertyFlags, kUseDefault, kLocalDoc);
}



v4.0.5





priint:comet InDesign® Plug-Ins, comet_pdf







frame::write_frame_info

itemlist::write_frame_info

itemlist::write_frame_info2

document::write_frame_info








static   int delete_frame_info(
 	ItemRef docRef,
 	ItemRef frameRef,
 	int frameSearchFlags = kUseDefault,
 	int documentType = kLocalDoc,
 	int conflictBehavior = kThrowError)



Delete frame infos from the data sources

More information at Frame infos







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






document

ItemRef
-

Document






frame

ItemRef
- 

Frame






frameSearchFlags

int
kUseDefault

How should the stored frame be identified?

See frame::apply_frame_info







documentType

int
kLocalDoc

How should the document source be identified?

See frame::apply_frame_info 







conflictBehavior

int
kThrowError

Behavior when multiple search results are found per frame 

Siehe frame::apply_frame_info





  #include "internal/frameinfos.h"




Delete the frame infos of the current frame from the data sources



#include "internal/frameinfos.h"

int main ()
{
    if (gRun > 1) { return 0; }
    frame::delete_frame_info(gDocument, gFrame);

    return 0;
}



v4.0.5 R8650





priint:comet InDesign® Plug-Ins, comet_pdf







frame::write_frame_info

frame::apply_frame_info

itemlist::delete_frame_info

itemlist::delete_frame_info2

document::delete_frame_info








static   int set_frameinfoid(ItemRef frame, char* value)



Sets the script tag with the key "frameInfoId" to the specified value







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Frame for which the tag should be set.






value

String or char*
- 

New value of the tag







v4.0.5 R8423





priint:comet InDesign® Plug-Ins







frame::apply_frame_info

frame::get_frameinfoid







static   char* get_frameinfoid(ItemRef frame)



Returns the value of the script tag with the key "frameInfoId".







Name
Type
Default
Description





Return

char*
 

Value of the tag






frameRef

ItemRef
-

Frame from which the tag should be gotten.







v4.0.5 R8423





priint:comet InDesign® Plug-Ins







frame::apply_frame_info

frame::set_frameinfoid







static   int prepare_translations(
 	ItemRef frameRef,
 	int placeholderID,
 	int autoStore,
 	int get_record_id_func,
 	IDType recordID,
 	int behavior = 0)



Like document::prepare_translations, but the function works in the text model of the given frame only.




Even if the frame is part of a text chain, the complete text is processed. Calling the function in a loop of a list frames therefor may change the text multiple times.







Please not, that the the example given in document::prepare_translations will work only insufficently for frames: The record will start at 100
for every call. To avoid this problem, use a globale variable here instead of the fix value.



v4.0.4 R8160, 18 Jun 2015





priint:comet InDesign® Plug-Ins







document::prepare_translations








static   int link_with_unique_placeholder(
 	ItemRef frameRef,
 	int placeholderID,
 	int autoStore,
 	int get_record_id_func,
 	IDType recordID)



Synonym for prepare_translations.




prepare_translations







static   int export_embedded_image(
 	ItemRef frameRef,
 	char*  path,
 	char*  outpath)



Export an embedded image into a file.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Valid frame


0 : Current script frame






path

String or char*
- 

Complete path of the image file. Existing files are overridden.






outpath

String or char*
0

Different embedded images can have different image formats. Therefor the image path given in path
can auomatically be extentend with the appropriate format extension


0 : Suppress adding extensions

allocated string : Add or replace the format extension. On successful return, outpath contains the
complete path of the generated file.







v4.0.5 R9813, 8 Jan 2016





priint:comet InDesign® Plug-Ins, comet_pdf











static   int export_html(
 	char* outputFolder,
 	char* outputName,
 	int startPos = 0,
 	int length = -1,
 	int copyImages = 0,
 	char* resultString = 0,
 	char* title = 0,
 	char* css = 0,
 	int flags = 0)



DEPRECATED! Please use the function html::export_ instead.Export the textmodel as an HTML file. Style information is put into a seperate .css file into a subfolder in the target folder.
More information can be found here.













Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
0

Frame






outputFolder

String or char*
-

Target folder






outputName

String or char*
-

Name of the target file (without extension)






startPos

int
0

Start index in the text model






length

int
-1

Length in the text model (-1 = until the end)






copyImages

int
0

Just link images or copy them? (0 = link, 1 = copy)






resultString

String or char*
0

Write the result to this string - when provided prevents writing to file






title

String or char*
0

Title for the html document (uses the filename by default)






css

String or char*
0

Use this as CSS (Either a path to a CSS file or a string containing styles)






flags

int
0

Additional export options

Combination of the following flags: 

kExportUnsupported (Non HTML-supported image formats are exported as .png)

kExportNonExisting (Non existing images are exported as .png from the previews)






  #include "internal/types.h"


Please use the function html::export_ instead.



4.0.5 R13882





priint:comet InDesign® Plug-Ins



textmodel::export_html








static   int has_linked_url(ItemRef frameRef = 0, char*  used_url = 0)



Does a frame have a Web Image?
General information about Web Images can be found here.







Name
Type
Default
Description





Return

int
 

0 : No or error

1 : Yes






frameRef

ItemRef
0

Valid frame reference


0 : current script frame






used_url

char* or String
0

On return, it contains the URL of image. Alloctaed char* or String or 0







v.4.0.5 R19777 (24. Jul 2017)

Parameter used_url seit v4.1 R23560 (16. Aug 2018)






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







itemlist::linked_urls
document::linked_urls








static   int has_embedded_url(ItemRef frameRef)



Check whether a frame has an embedded Web Image.
General information about Web Images can be found here.







Name
Type
Default
Description





Return

int
 

0 : No or error

1 : Yes






frameRef

ItemRef
-

Valid frame.


0 : current script frame







v4.0.5 R19777, 20. Jul 2017





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



itemlist::embedded_urls
document::embedded_urls








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



Place a URL based file into a frame. The URL is downloaded and then linked into the document.
General information about Web Images can be found here.




The download is done by default without a progress bar.
With prefs::show_url_progress you can enable the progress bar for URL downloads.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Frame in which the image is to be inserted
0 : current script frame






url

char*
-

Valid URL (http, https, ftp, ftps)






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.

-1 : Use pathname

≥ 0 : 0-based clipping path index. Values > 0 are ignored by comet_pdf here. Comet_pdf uses the path defined by \span[src]{pathname instead.}






pathname

String or char*
""

Name of clipping path


Values ignored by InDesign® if the path is defined by its index already (pathindex ≥ 0).






⇨ Properties for clipping. Also used for alpha channels.






flags

int
0

How to clip the image? T%he parameter is a bit field, so values can be added.


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

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

kRestrictToFrameFlag


Value is ignored by comet_pdf.






cliptoFrame

int
0

Use the the clipping path as the frames path?


0 : Keep old frame 

1 : Change frame






tolerance

float
0.0

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


The parameter is not applied by Indesign® Server and comet_pdf.






minPathSize

float
0.0

subpaths smaller than the minPathSize will be deleted.


The parameter is not applied by Indesign® Server and comet_pdf.






inset

float
0.0

How far to inset the path


The parameter is not applied by Indesign® Server and comet_pdf.






⇨ Alpha Channel






alphaIndex

int
0

0-based index of channel, see image::alpha_channel_index


kIgnoreClipping : Leave the alpha channel unchanged.

kResetClipping : Reset alpha channel when inserting the image.

-1 : Use the value of alphaChannel
≥ 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 if the channel is defined by its index already (e.g. alphaIndex ≥ 0).






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.
Alternatively, you can also add the value kAllowHolesFlag to src{flags}.






⇨ Update Flags






updateFlags

int 
0

For Web-Images Only


16 : If the local image file already exists, it is used without further checkings.





  #include "internal/types.h"





int main ()
{
    String	str 	= string::alloc ();
    int 	result;

    if (!system::shiftkey ())
    {
        frame::gettext (gFrame, str);
        result = frame::link_url (gFrame, string::get (str), 9, 0.0);
        string::release (str);
    }
    else
    {
        frame::check_url_link (gFrame);
    }

    return 0;
}



v.4.0.5 R19777 (24. Jul 2017)

Parameter updateFlags since v4.3 R34200, 23. Jan 2024





priint:comet InDesign® Plug-Ins, comet_pdf







document::get_image_url_folder
document::check_url_links
document::update_url_links
frame::has_linked_url
frame::has_embedded_url,
frame::check_url_link
frame::get_url,
prefs::show_url_progress








static   int embed_url(
 	ItemRef frameRef,
 	char*  url,
 	int alignment = 5,
 	float boundingBox = 0.0,
 	char*  formatString = 0)



 MAGIC  Import an embedded image from an URL.
General information about Web Images can be found here..
The image is inserted directly into the document via an URL. The following URLs are supported:




File-URLs and normal paths are imported directly using frame::embed_file without
any information about the original image.




If the frame has an URL already, you can call the function with an empty URL ("" or 0). This
is usefull in the following cases:



    

  1. User 1 knows the URL and embeds the image.

  2. User 1 sends the document to user 2 at place B.

  3. User 2 can update the images without knowings its URLs.




Frames must not contain the embeded image itself to be update-able. The URL is enough.




If the new image has the same proportions like the old one, position, rotation,
scaling and skew of the old image are applied to the new image. Otherwise the placement infos of the function call are used.




The download is done by default without a progress bar.
With prefs::show_url_progress you can enable the progress bar for URL downloads.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Valid frame. If the frame isn't a Graphic Frame, it will be converted automatically


0 : current script frame






url

char*
-

Complete URL to the image


"" : If the frames contains an image URL already, the URL can be empty.






alignment

int
kMiddle

see image positions






boundingBox

float
kFitBigContentProp

Image size in points


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


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


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






formatString

char*
0

Used only in comet_pdf. Image format given in common imge file extensions like "png", or "jpeg".
The value is only used in later calls to export_embedded_image.





  #include "internal/types.h"




Embed an image given by an URL.



#include "internal/types.h"

int main ()
{
    String	str 	= string::alloc ();
    int 	result;
    if (!system::shiftkey ())
    {
        frame::gettext (gFrame, str);
        result = frame::embed_url (gFrame, string::get (str), 9, 0.0, 0);
        string::release (str);
    }
    else
    {
        frame::check_url_link (gFrame);
    }

    return 0;
}



v4.0.5 R19777, 20. Jul 2017





priint:comet InDesign® Plug-Ins, comet_pdf
R





embed_file
has_embedded_url
remove_url_link
itemlist::embed_urls








static   int check_url_link(ItemRef frameRef, int*  state)



Check whether the image is a Web Image and was changed on server side.
General information about Web Images can be found here.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frameRef

ItemRef
-

Valid frame reference
0 : current script frame






state

int*
-

After execution, this indicates the state of the Web Image


-1: Error while checking status

0: Ok

1: Out of date, need update







v.4.0.5 R19777 (24. Jul 2017)





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







itemlist::check_url_links
document::check_url_links








static   int update_url_link(ItemRef frameRef, int flags)



Update a Web Image.
General information about Web Images can be found here..







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frame

ItemRef
-

Frame to be updated






flags

int
0

1: Show progress bar







v.4.0.5 R19777 (24. Jul 2017)





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





itemlist::update_url_links
document::update_url_links








static   int remove_url_link(ItemRef frameRef)



Remove the link to a Web Image from the frame.
The image in the frames is untouched, only the original image address (its URL) is removed.
General information about Web Images can be found here..







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






frame

ItemRef
-

Valid frame reference







v.4.0.5 R19777 (24. Jul 2017)





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





itemlist::remove_url_links
document::remove_url_links








static   char* get_url(ItemRef frameRef = 0)



Get the web address (URL) stored behind the frame.
General information about Web Images can be found here.







Name
Type
Default
Description





Return

char*
 

Web address (URL) of image

The return value is read only, do NOT CHANGE.
The result will be overridden on following calls to the function.
See here to learn more about functions returning r/o char* values.







frameRef

ItemRef
0

Valid frame reference
0 : current script frame







v.4.0.5 R19777 (24. Jul 2017)





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







document::get_image_url_folder
document::check_url_links
document::update_url_links
frame::get_url
frame::has_linked_url
frame::has_embedded_url








static   char* get_url_importresult(ItemRef frameRef = 0)



Get the last import result of a We Image.
General information about Web Images can be found here.







Name
Type
Default
Description





Return

char*
 

Last import result..

The return value is read only, do NOT CHANGE.
The result will be overridden on following calls to the function.
See here to learn more about functions returning r/o char* values.







frameRef

ItemRef
0

Valid frame reference
0 : current script frame










int main ()
{
    if (frame::has_linked_url (gFrame) || frame::has_embedded_url (gFrame))
    {
        showmessage ("Frame %d\nURL\t\t: %s\nState\t\t: %d\nAlign\t\t: %d\nSzInfo\t\t: %f\nTimestamp\t: %s\nImported\t\t: %s\nResult\t\t: %s",
         			item::getint (gFrame),
         			frame::get_url (gFrame),
         			frame::get_url_state (gFrame),
         			frame::get_url_alignment (gFrame),
         			frame::get_url_sizeinfo (gFrame),
         			frame::get_url_filedate (gFrame),
         			frame::get_url_importdate (gFrame),
         			frame::get_url_importresult (gFrame));
    }
    else
    {
        showmessage ("No Web Image in frame");
    }
    return 0;
}


v.4.0.5 R19777 (24. Jul 2017)





priint:comet InDesign® Plug-Ins, comet_pdf







document::get_image_url_folder
document::check_url_links
document::update_url_links
frame::get_url
frame::has_linked_url
frame::has_embedded_url








static   int get_url_state(ItemRef frameRef = 0, int doCheck = 1)



Get the last import result of a Web Image.
General information about Web Images can be found here.







Name
Type
Default
Description





Return

int
 

0 : Okay

1 : Image changed on server

2 : Image not available






frameRef

ItemRef
0

Valid frame reference
0 : current script frame






doCheck

int
1

Check state before


0 : No

1 : Yes










int main ()
{
    if (frame::has_linked_url (gFrame) || frame::has_embedded_url (gFrame))
    {
        showmessage ("Frame %d\nURL\t\t: %s\nState\t\t: %d\nAlign\t\t: %d\nSzInfo\t\t: %f\nTimestamp\t: %s\nImported\t\t: %s\nResult\t\t: %s",
         			item::getint (gFrame),
         			frame::get_url (gFrame),
         			frame::get_url_state (gFrame),
         			frame::get_url_alignment (gFrame),
         			frame::get_url_sizeinfo (gFrame),
         			frame::get_url_filedate (gFrame),
         			frame::get_url_importdate (gFrame),
         			frame::get_url_importresult (gFrame));
    }
    else
    {
        showmessage ("No Web Image frame");
    }
    return 0;
}


v.4.0.5 R19777 (24. Jul 2017)





priint:comet InDesign® Plug-Ins, comet_pdf







document::get_image_url_folder
document::check_url_links
document::update_url_links
frame::get_url
frame::has_linked_url
frame::has_embedded_url








static   int get_url_alignment(ItemRef frameRef = 0)



Get the initial alignment of the Web Image.
General information about Web Images can be found here.







Name
Type
Default
Description





Return

int
 

Initial alignment






frameRef

ItemRef
0

Valid frame reference
0 : current script frame










int main ()
{
    if (frame::has_linked_url (gFrame) || frame::has_embedded_url (gFrame))
    {
        showmessage ("Frame %d\nURL\t\t: %s\nState\t\t: %d\nAlign\t\t: %d\nSzInfo\t\t: %f\nTimestamp\t: %s\nImported\t\t: %s\nResult\t\t: %s",
         			item::getint (gFrame),
         			frame::get_url (gFrame),
         			frame::get_url_state (gFrame),
         			frame::get_url_alignment (gFrame),
         			frame::get_url_sizeinfo (gFrame),
         			frame::get_url_filedate (gFrame),
         			frame::get_url_importdate (gFrame),
         			frame::get_url_importresult (gFrame));
    }
    else
    {
        showmessage ("No Web Image in frame");
    }
    return 0;
}


v.4.0.5 R19777 (24. Jul 2017)





priint:comet InDesign® Plug-Ins, comet_pdf







document::get_image_url_folder
document::check_url_links
document::update_url_links
frame::get_url
frame::has_linked_url
frame::has_embedded_url








static   char* get_url_filedate(ItemRef frameRef = 0)



Get the time stamp of the original file of a Web Image. The time stamp may be change on server in the mean time. To get
the current time stamp call get_url_state before.
General information about Web Images can be found here.







Name
Type
Default
Description





Return

char*
 

time stamp of original file in web

The return value is read only, do NOT CHANGE.
The result will be overridden on following calls to the function.
See here to learn more about functions returning r/o char* values.







frameRef

ItemRef
0

Valid frame reference
0 : current script frame










int main ()
{
    if (frame::has_linked_url (gFrame) || frame::has_embedded_url (gFrame))
    {
        showmessage ("Frame %d\nURL\t\t: %s\nState\t\t: %d\nAlign\t\t: %d\nSzInfo\t\t: %f\nTimestamp\t: %s\nImported\t\t: %s\nResult\t\t: %s",
         			item::getint (gFrame),
         			frame::get_url (gFrame),
         			frame::get_url_state (gFrame),
         			frame::get_url_alignment (gFrame),
         			frame::get_url_sizeinfo (gFrame),
         			frame::get_url_filedate (gFrame),
         			frame::get_url_importdate (gFrame),
         			frame::get_url_importresult (gFrame));
    }
    else
    {
        showmessage ("No Web Image in frame");
    }
    return 0;
}


v.4.0.5 R19777 (24. Jul 2017)





priint:comet InDesign® Plug-Ins, comet_pdf







document::get_image_url_folder
document::check_url_links
document::update_url_links
frame::get_url
frame::has_linked_url
frame::has_embedded_url








static   char* get_url_importdate(ItemRef frameRef = 0)



When was the last time the Web Image was imported?

Format: DD.MM.YYYY HH:MM:SS

e.g. 03.12.1986 14:32:47



General information about Web Images can be found here.







Name
Type
Default
Description





Return

char*
 

Last time the file was imported


The return value is read only, do NOT CHANGE.
The result will be overridden on following calls to the function.
See here to learn more about functions returning r/o char* values.







frameRef

ItemRef
0

Valid frame reference
0 : current script frame










int main ()
{
    if (frame::has_linked_url (gFrame) || frame::has_embedded_url (gFrame))
    {
        showmessage ("Frame %d\nURL\t\t: %s\nState\t\t: %d\nAlign\t\t: %d\nSzInfo\t\t: %f\nTimestamp\t: %s\nImported\t\t: %s\nResult\t\t: %s",
         			item::getint (gFrame),
         			frame::get_url (gFrame),
         			frame::get_url_state (gFrame),
         			frame::get_url_alignment (gFrame),
         			frame::get_url_sizeinfo (gFrame),
         			frame::get_url_filedate (gFrame),
         			frame::get_url_importdate (gFrame),
         			frame::get_url_importresult (gFrame));
    }
    else
    {
        showmessage ("No image URL in frame");
    }
    return 0;
}


v.4.0.5 R19777 (24. Jul 2017)





priint:comet InDesign® Plug-Ins, comet_pdf













static   float get_url_sizeinfo(ItemRef frameRef = 0)



Initial size hint of Web Image.
General information about Web Images can be found here.















Name
Type
Default
Description





Return

int
 

Initial size hint of  the Web Image.






frameRef

ItemRef
0

Valid frame reference
0 : current script frame










int main ()
{
    if (frame::has_linked_url (gFrame) || frame::has_embedded_url (gFrame))
    {
        showmessage ("Frame %d\nURL\t\t: %s\nState\t\t: %d\nAlign\t\t: %d\nSzInfo\t\t: %f\nTimestamp\t: %s\nImported\t\t: %s\nResult\t\t: %s",
         			item::getint (gFrame),
         			frame::get_url (gFrame),
         			frame::get_url_state (gFrame),
         			frame::get_url_alignment (gFrame),
         			frame::get_url_sizeinfo (gFrame),
         			frame::get_url_filedate (gFrame),
         			frame::get_url_importdate (gFrame),
         			frame::get_url_importresult (gFrame));
    }
    else
    {
        showmessage ("No Web Image in frame");
    }
    return 0;
}


v.4.0.5 R19777 (24. Jul 2017)





priint:comet InDesign® Plug-Ins, comet_pdf







document::get_image_url_folder
document::check_url_links
document::update_url_links
frame::get_url
frame::has_linked_url
frame::has_embedded_url








static   int doclink::get(ItemRef fr, ItemRef lk)



Get a frame's link.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode


noImageErr (101) : The frame is not an image






fr

ItemRef
-

Valid frame reference






lk

ItemRef
-

Allocated link reference for the result


In InDesign® this reference is not a document frame.
You can use the result only in the other doclink methods.
Using it in other frame methods will cause execution errors!
To get the links document frame, please use frame::doclink::get_frame.


In comet_pdf the reference contains the input frame fr in case of success and
can (besides the doclink methods) be used directly in all other frame functions .










#pragma plain
#include "internal/types.h"

int main ()
{
    ItemList	lks		= itemlist::alloc ();
    ItemRef		lk		= item::alloc ();
    ItemRef		fr		= item::alloc ();
    char		p		[5000];
    int			i;

    document::get_links (0, 0, "", lks);
    wlog ("", "%d links found\n", itemlist::length (lks));

    for (i = 0; i < itemlist::length (lks); i++)
    {
        itemlist::get (lks, lk, i);
        frame::doclink::get_frame (lk, fr);
        frame::doclink::get_path (lk, p);
        wlog ("", "Link %d\t-> %d [type = %d, state = %d, path = '%s']\n",
         	item::getint (lk),
         	item::getint (fr),
         	frame::doclink::get_type (lk),
         	frame::doclink::get_state (lk),
         	p);
    }

    return 0;
}


v3.3 R2550, 30.06.2011

Support for comet_pdf since v4.2 R32078, 28. Dec 2022





priint:comet InDesign® Plug-Ins, comet_pdf







doclink::get_frame

document::get_links

comet.CFrame.getDocLink








static   int doclink::get_frame(ItemRef lk, ItemRef fr)



Get the frame of a link.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






lk

ItemRef
-

valid link reference






fr

ItemRef
-

allocted frame reference for the result







v3.3 R2550, 30.06.2011

Support for comet_pdf since v4.2 R32078, 28. Dec 2022





priint:comet InDesign® Plug-Ins, comet_pdf





doclink::get

document::get_links

comet.CDocLink.getFrame








static   int doclink::get_state(ItemRef lk)



Get the state of a frame link.







Name
Type
Default
Description





Return

int
 

Current link state


-1 : Error

0 : Link is up-to-date and available for use.

1 : Link is out-of-date and needs to be updated

2 : Link resource is embedded, and link is up-to-date.

3 : Link resource is cached, and link is up-to-date.

4 : Link resource is contained, and link is up-to-date.

5 : Link resource is missing.

6 : Link resource is not accessible by the user.

7 : Link resource state is pending an update.

8 : Link resource state cannot be determined.


comet_pdf does only support the states -1 (Error), 0 (Image file exists), 2 (Embedded) und 5 (Image file missing).






lk

ItemRef
-

valid link reference










#pragma plain
#include "internal/types.h"

int main ()
{
    ItemList	lks		= itemlist::alloc ();
    ItemRef		lk		= item::alloc ();
    ItemRef		fr		= item::alloc ();
    char		p		[5000];
    int			i;

    document::get_links (0, 0, "", lks);
    wlog ("", "%d links found\n", itemlist::length (lks));

    for (i = 0; i < itemlist::length (lks); i++)
    {
        itemlist::get (lks, lk, i);
        frame::doclink::get_frame (lk, fr);
        frame::doclink::get_path (lk, p);
        wlog ("", "Link %d\t-> %d [type = %d, state = %d, path = '%s']\n",
         	item::getint (lk),
         	item::getint (fr),
         	frame::doclink::get_type (lk),
         	frame::doclink::get_state (lk),
         	p);
    }

    return 0;
}


v3.3 R2550, 30.06.2011

Support for comet_pdf since v4.2 R32078, 28. Dec 2022





priint:comet InDesign® Plug-Ins, comet_pdf







document::get_links

comet.CDocLink.getState








static   int doclink::get_type(ItemRef lk)



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



Links to text frames are not supported by comet_pdf!







Name
Type
Default
Description





Return

int
 

Current link type


-1 : Error

0 : Internal

1 : Image

2 : Text Frame







lk

ItemRef
-

valid link reference










#pragma plain
#include "internal/types.h"

int main ()
{
    ItemList	lks		= itemlist::alloc ();
    ItemRef		lk		= item::alloc ();
    ItemRef		fr		= item::alloc ();
    char		p		[5000];
    int			i;

    document::get_links (0, 0, "", lks);
    wlog ("", "%d links found\n", itemlist::length (lks));

    for (i = 0; i < itemlist::length (lks); i++)
    {
        itemlist::get (lks, lk, i);
        frame::doclink::get_frame (lk, fr);
        frame::doclink::get_path (lk, p);
        wlog ("", "Link %d\t-> %d [type = %d, state = %d, path = '%s']\n",
         	item::getint (lk),
         	item::getint (fr),
         	frame::doclink::get_type (lk),
         	frame::doclink::get_state (lk),
         	p);
    }

    return 0;
}


v4.1.6 R26314, 22. Nov 2019

Support for comet_pdf since v4.2 R32078, 28. Dec 2022





priint:comet InDesign® Plug-Ins, comet_pdf







document::get_links

comet.CDocLink.getType








static   int doclink::get_path(ItemRef lk, char*  fullpath)



Get the complete path of a link reference.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






lk

ItemRef
-

valid link reference






fullpath

String or char*
-

Allocated string for the result string (the complete path to the linked file)


The result depends on the type of the link, see doclink::get_type:

    

  1.  (Internal) : UID of the text frame (as char* or string!), InDesign® only

  2.  (Image) : Full path to the linked image

  3.  (Text Frame) : Empty (""), InDesign® only


Embedded images with a reference to their original file provide
the path of this original file.







v3.3 R2550, 30.06.2011

Support for comet_pdf since v4.2 R32078, 28. Dec 2022





priint:comet InDesign® Plug-Ins, comet_pdf





document::get_links

comet.CDocLink.getPath








static   int doclink::update(ItemRef lk)



Update the link by reimporting the data.
The update uses the setting last used to import the data.
If this fails because the data is no longer appropriate for
this import filter, the import uses the standard import code
which picks a new filter.




For comet_pdf the command is available but does not execute anything.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






lk

ItemRef
-

valid link reference










#pragma plain
#include "internal/types.h"

int main ()
{
    ItemList	lks		= itemlist::alloc ();
    ItemRef		lk		= item::alloc ();
    ItemRef		fr		= item::alloc ();
    char		p		[5000];
    int			i;

    document::get_links (0, 0, "", lks);
    wlog ("", "%d links found\n", itemlist::length (lks));

    for (i = 0; i < itemlist::length (lks); i++)
    {
        itemlist::get (lks, lk, i);
        frame::doclink::get_frame (lk, fr);
        frame::doclink::get_path (lk, p);
        wlog ("", "Link %d\t-> %d [type = %d, state = %d, path = '%s']\n",
         	item::getint (lk),
         	item::getint (fr),
         	frame::doclink::get_type (lk),
         	frame::doclink::get_state (lk),
         	p);
    }

    return 0;
}


v3.3 R2550, 30.06.2011

Support for comet_pdf since v4.2 R32078, 28. Dec 2022





priint:comet InDesign® Plug-Ins, comet_pdf







document::get_links

comet.CDocLink.update








static   int doclink::relink(ItemRef lk, char* path)



Import a new image into the link. The function corresponds to frame::image with the frame of
the doclink object and the placement kPlaceLikeExisting.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






lk

ItemRef
-

valid link reference






fullpath

char* oder String
-

complete path to image







v4.1 R24141, 20. Nov 2018

Support for comet_pdf since v4.2 R32078, 28. Dec 2022





priint:comet InDesign® Plug-Ins, comet_pdf







document::get_links

comet.CDocLink.relink








static   int doclink::copy_to_folder(
 	ItemRef lk,
 	char*  destPath,
 	int relink = 0)



Copies links' resources to the specified folder, and optionally relinks the resources.













Name
Type
Default
Description





Return

int
 

0 or ErrorCode
-1122 : kCannotCopyLinkToFolderErr






lk

ItemRef
-

valid link reference






destPath

String or char*
-

Complete path to the destination folder. The folder is created if it does not exist.






relink

int
0

Update link??


0 : no, leave it untouched

1 : Yes, the link should point to duplicated file










int main ()
{
    ItemList  		lks    	= itemlist::alloc ();
    ItemRef      	lk     	= item::alloc ();
    int           	i;

    document::get_links (0, 0, "", lks);

    for (i = 0; i < itemlist::length (lks); i++)
    {
        itemlist::get (lks, lk, i);
        frame::doclink::copy_to_folder (lk, "$DESKTOP/aaabbb", 1);
    }

    return 0;
}


v3.3 R2550, 30.06.2011

Support for comet_pdf since v4.2 R32078, 28. Dec 2022





priint:comet InDesign® Plug-Ins, comet_pdf







document::get_links








static   int note::get_dest(
 	ItemRef nt,
 	int*  type = 0,
 	int*  dest = 0)



Determine the type and destination of a Comet Note.




The note is defined by its document reference (not its ID).
In InDesign®, this reference corresponds to the document frame.
In comet_pdf the reference points directly to the note object
(and must not be used in frame functions under any circumstances therefore!).
Valid references to Comet Notes can be obtained using the itemlist::~_notes functions.


About editing notes by their IDs, see \URL[here].{document.html#notes::find}.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






nt

ItemRef
-

Valid note reference. Notes can be fetched with the itemlist::~_notes functions.






type

int*
0

If executed successfully, the variable contains the type of the note:


kNoteTypePage

kNoteTypePageIndex

kNoteTypeGroup

kNoteTypeFrame






dest

int*
0

On successful execution, the variable contains the note's destination as an integer..


With item::define you can make the result an ItemRef for frame and page notes.





  #include "internal/types.h"





Get all Comet notes of a document.



#include "internal/types.h"

int main ()
{
    ItemRef 		fr		= item::alloc ();
    int           	i, tyte, dest, result;
    ItemList 		notes;

    if (gRun > 1)	return 0;

    notes = itemlist::doc_notes ();
    itemlist::select (notes);

    for (i = 0; i < itemlist::length (notes); i++)
    {
        itemlist::get (notes, fr, i);
        frame::note::get_dest (fr, &type, &dest);
        wlog ("", "Note	%d : Type = %d, Dest = %d\n", item::getint (fr), type, dest);
    }

    itemlist::release (notes);
    item::release (fr);

    return 0;
}


v4.2 R32080, 2. Jan 2023





priint:comet InDesign® Plug-Ins, comet_pdf







itemlist::doc_notes
itemlist::page_notes
itemlist::group_notes
itemlist::frame_notes

frame::note::change_dest
frame::note::remove

document::notes::find
document::notes::delete_note








static   int note::change_dest(
 	ItemRef nt,
 	int type,
 	int dest)



Change the destination of a Comet Note.
The function checks if the target exists before changing it and returns an error code if the target is missing.
After successful relinking, the note is moved to the correct page and realigned to the target if necessary.




The note is defined by its document reference (not its ID).
In InDesign®, this reference corresponds to the document frame.
In comet_pdf the reference points directly to the note object
(and must not be used in frame functions under any circumstances therefore!).
Valid references to Comet Notes can be obtained using the itemlist::~_notes functions.


About editing notes by their IDs, see \URL[here].{document.html#notes::find}.







Name
Type
Default
Description





Return

int
 

0 or ErrorCode






nt

ItemRef
-

Valid note reference. Notes can be fetched with the itemlist::~_notes functions.






type

int
-

New type of note. The following specifications are allowed:


kNoteTypePage

kNoteTypePageIndex

kNoteTypeGroup

kNoteTypeFrame






dest

int
-

New reference target. Please note that an integer is always expected.


For Frame Notes (kNoteTypeFrame) get the corresponding specification using item::getint.


For Page Notes (kNoteTypePage), get the corresponding specification using page::get_uid.


Page indexes (kNoteTypePageIndex) are always 1-based.





  #include "internal/types.h"





Relink all Comet Notes of the Comet Group of the current frame to Comet Group 25185.



#include "internal/types.h"

int main ()
{
    ItemRef 		fr		= item::alloc ();
    int           	i;
    ItemList 		notes;

    if (gRun > 1)	return 0;

    notes	= itemlist::group_notes ();
    for (i = 0; i < itemlist::length (notes); i++)
    {
        itemlist::get (notes, fr, i);
        frame::note::change_dest (fr, kNoteTypeGroup, 25185);
    }

    itemlist::select (notes);

    return 0;
}





Move all page-indexed Comet Notes to page 1. Then do 'something' with page deletion etc.. Then create new pages.
And finally move the notes back to the page where they were at the beginning. If the page is missing in the meantime, the note is deleted.



#include "internal/types.h"

int change_pageindex (ItemList notes, int pindex)
{
    ItemRef 		fr			= item::alloc ();
    int				n, result;

    for (n = 0; n < itemlist::length (notes); n++)
    {
        itemlist::get (notes, fr, n);
        result = frame::note::change_dest (fr, kNoteTypePageIndex, pindex);
        if (result != 0)
        {
            frame::note::remove (fr);
        }
    }

    item::release (fr);

    return 0;
}
int main ()
{
    int				pages		= document::pages ();
    int 			p;
    ItemListList	allNotes	= itemlistlist::alloc ();
    ItemList		notes;

    if (gRun > 1)	return 0;
    if (pages == 1)	return 0;

    document::notes::show ();

    // Page 1 will certainly not be deleted.
    // So move all notes to page index 1
    //
    for (p = 2; p <= pages; p++)
    {
        notes = itemlist::page_notes (0, p, kNoteTypePageIndex);
        itemlistlist::append (allNotes, notes);	// Remember those notes
        change_pageindex (notes, 1);
    }

    // For testing purposes remove all pages except the first one
    //
    for (p = 2; p <= pages; p++)
    {
        page::remove (2);
    }

    // Then create one page less than before
    //
    page::create (pages-2);

    // And move back all notes to their old pages.
    // Superfluous notes are deleted.
    //
    p = 2;
    for (notes = itemlistlist::first (allNotes); notes; notes = itemlistlist::next (allNotes))
    {
        change_pageindex (notes, p);
        itemlist::release (notes);		// We don't need this list anymore
        p++;
    }

    // Clean up
    //
    itemlistlist::release (allNotes);

    return 0;
}


v4.2 R32080, 2. Jan 2023





priint:comet InDesign® Plug-Ins, comet_pdf







itemlist::doc_notes
itemlist::page_notes
itemlist::group_notes
itemlist::frame_notes

frame::note::get_dest
frame::note::remove

document::notes::find
document::notes::delete_note








static   int note::remove(ItemRef nt)



Remove a Comet Note from the document.




The note is defined by its document reference (not its ID).
In InDesign®, this reference corresponds to the document frame.
In comet_pdf the reference points directly to the note object
(and must not be used in frame functions under any circumstances therefore!).
Valid references to Comet Notes can be obtained using the itemlist::~_notes functions.


About editing notes by their IDs, see \URL[here].{document.html#notes::find}.












Name
Type
Default
Description





Return

int
 

0 or ErrorCode






nt

ItemRef
-

Reference of the note to be deleted. Notes can be fetched with the itemlist::~_notes functions.







v4.2 R32080, 2. Jan 2023





priint:comet InDesign® Plug-Ins, comet_pdf







itemlist::doc_notes
itemlist::page_notes
itemlist::group_notes
itemlist::frame_notes

frame::note::get_dest
frame::note::change_dest

document::notes::find
document::notes::delete_note





  #include "internal/types.h"





The following example illustrates some of the typical frame commands. The illustration shows the result of the script execution.





#include "internal/types.h"

main ()
{
    ItemRef		frame	= item::alloc ();
    ItemRef		frame2	= item::alloc ();
    char		layerName[256];
    char		tt[2000];
    int			result; 

    color::define ("Dark orange", 	255, 90, 0);
    color::define ("Orange", 		255, 127, 0);
    color::define ("Light orange", 	255, 190, 0); 

    result 	= frame::create_textframe (
     				frame,
     				10, 10, 200, 200,
     				document::page (),
     				layer::name (2, layerName));
    if (result != 0)
    {
        showmessage ("Error %d",result);
        item::release (frame);
        return;
    } 

    frame::star 	(frame, 21, 10);
    frame::color 	(frame, "Orange");
    frame::stroke 	(frame, "Orange", 1.5);
    frame::shadow 	(frame, "Dark orange",
     				50.0, 1, // tint, blendmode
     				8.3, 9.3,// xd, yd
     				3.0);	 // blur 

    result 	= frame::create_textframe (
     				frame2,
     				10, 210, 300, 400
     				document::page (),
     				layer::name (2, layerName)); 

    frame::color 	(frame2, "Light orange");
    frame::stroke 	(frame2, "Orange", 12.3);
    frame::shadow 	(frame2, "Dark orange",
     				50.0, 1, // tint, blendmode
     				8.3, 9.3,// xd, yd
     				3.0);	 // blur
    frame::vignette (frame2, 3, 10.0, 1, 100.0, 100.0); 

    frame::link (frame, frame2); 

    tt = "%!TT<ParaStyle:description>";
    tt += "The globe thistle in Latin is called ";
    tt += "<CharStyle:batch name><w2:1,3, -22, -33>X</w2>";
    tt += "<CharStyle:> And this is how is looks : "; 

    tt += "#<in: 100.0, 100.0, 11,  3, -66, -99>Trulla du!</in>#"; 

    tt += "*<in: 100.0, 100.0>";
    tt += "%!TT<ParaStyle:description>";
    tt += "What does the sub-frames say about chicory? ";
    tt += "<CharStyle:batch name><w2:1,1, -22, -33>X</w2>! <CharStyle:>";
    tt += "Ah yes, of course!";
    tt += "</in>"; 

    tt += "*Good, eh?"; 

    frame::insert (frame, tt, 0, true); 

    item::release (frame);
    item::release (frame2);

    return 0;
}





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




 ⇒ 



#include "internal/types.h"

int main ()
{
    ItemRef		groupRef	= item::alloc ();
    ItemRef		newframe	= item::alloc ();
    ItemList	grouped		= itemlist::alloc ();
    float		l, t, r, b;
    char		lay[256];

    if (gRun > 1) return 0;

    if (frame::get_group (gFrame, groupRef))
    {
        showmessage ("frame not grouped");
        return 0;
    }
    frame::ungroup (groupRef, grouped);

    itemlist::bbox (grouped, &l, &t, &r, &b);
    frame::create2 (
     		newframe,
     		kStar,
     		r+10.0, t, r+130.0, t+120.0,
     		page::get (gFrame),
     		frame::get_layer (gFrame, lay),
     		0,	// columns
     		0,	// vertical?
     		0.0,	// gutter
     		5, 40);

    frame::color_rgb (newframe, 255, 0, 0, 0);
    frame::stroke_rgb (newframe, 0, 0, 0, 5.0);
    itemlist::append (grouped, newframe);

    frame::group (grouped, gOutFrame);

    return 0;
}




Paul Seidel, Thanks to Joseph!



17.12.2024, 12:52 Uhr



Plugin Version 1.0.10




Alphabetic index HTML hierarchy of classes or Java