Pages and page numbers of a document

Version :
06.02.2024, 10:21 Uhr

Pages and page numbers of a document

static int get(ItemRef itemRef = 0, int queryNearest = 0)

Ascertain the (1-based) page index of a document object or the current index of the current front of the document itself. The current page of the document is designated as that page which occupies the upper left corner of the document window. InDesign® Server works without a user interface and returns 1 as front page! Page indexes begin with 1, independent of the start page number set for the document.

Attention: Page numbers of Inlines depend on the current anchor position. comet_pdf must start an additional renderer run for this function and the function is therefore very time-consuming! In case of frames with activated text tet wraps above the text, the page of Inlines cannot be calculated without errors at the moment by comet_pdf.

Name Type Default Description
Return int   Page number (1-based)

0 : no page
itemRef ItemRef 0 Get the current page number or that on which the specified element is located

0 : Current page
Otherwise : page of itemRef

Using InDesign® Server or comet_pdf the current front page is undefined!

queryNearest int 0 Result if the frame is not on any page

0 : no page
1 : nearest page
int pg = page::get ([itemRef]);

Parameter queryNearest since v3.3 R3116, 10. Aug. 2012

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

page::get_str
item
comet.CFrame.getPage

static int get_uid(
  ItemRef docRef,
  int pnum,
  ItemRef resultRef = 0)

Get the UID of a document page.

Name Type Default Description
Return int   UID of the searched page

0 : Error or page not found
docRef ItemRef - Document reference

0 : Current front document
pnum int - 1-based page number in document
resultRef ItemRef 0 Allocated ItemRef for the result. The UID of the result (item::getint) is equal to the return value of the function.

0 : Not required (but the return value still contains the searched UID)

v4.1.6, 28. Sep 2019

priint:comet InDesign® Plug-Ins, comet_pdf

page::get
page::get_str
item
comet.CPage.getUID

static char* get_str(
  char* str,
  ItemRef itemRef,
  int inclSection = 1,
  int useIntStyle = 1,
  int pgNumType = 0,
  int abbrev = 1)

Ascertain the name of the page of a document object or the name of the documents current front page. The current page of the document is designated as that page which occupies the the upper left corner of the document window. In InDesign ® Server the function returns an empty string.

Name Type Default Description
Return String or char*   (Depends on Parameter str)* Page name, same as str
str String or char* - Memory for the result
itemRef ItemRef - Frame reference or 0, 0 = current page number of the script text model or frame.
inclSection int 1 Is the section name to be retained ?
Ignored by Illustrator.
useIntStyle int 1 1 : Use arabic numerals in string;
0 : use the style of this section
Ignored by Illustrator.
pgNumType int 0 Which page settings are to be used?
0 : InDesign® settings
1 : Document settings
2 : Pages counted beginning from 1
Ignored by Illustrator.
abbrev int 1 Use abbreviation?
Ignored by Illustrator.
str = page::get_str (str, itemref
 	[, inclSectName
 	[, useIntStyle
 	[, pgNumType [, abbrev]]]]);


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

page::get
get_str_by_index
item
comet.CPage.getName

static char* get_str_by_index(
  char* str,
  ItemRef docRef,
  int pageNum,
  int inclSection = 1,
  int useIntStyle = 1,
  int pgNumType = 0,
  int abbrev = 1)

Ascertain the page name of a document page given by its 1-based index.

Name Type Default Description
Return String or char*   (Depends on Parameter str) Page name, same as str
str String or char* - Memory for the result
docRef ItemRef - Document reference
0 : current document
pageNum int - 1-based page index
inclSection int 1 Is the section name to be retained ?
Ignored by Illustrator.
useIntStyle int 1 1 : Use arabic numerals in string;
0 : use the style of this section
Ignored by Illustrator.
pgNumType int 0 Which page settings are to be used?
0 : InDesign® settings
1 : Document settings
2 : Pages counted beginning from 1
Ignored by Illustrator.
abbrev int 1 Use abbreviation?
Ignored by Illustrator.

A more or less senseless call, index contains the given page index as string after it ("10").

char		index [256];
:
page::get_str_by_index (index, 0, 10, 0, 1, 2, 1);

Version 2.1 R1789, 2. March 2010

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

page::get_str

static int set_number(
  ItemRef docRef,
  int pageNum,
  int startNum = -1,
  char* name = "--ignore--",
  char* marker = "--ignore--",
  int style = -1,
  int continuePrevious = -1,
  int includeSectionPrefix = -1)

Set the page number and page number style of a given page. Calls to this function my change the page type.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Destination document
0 : current froint document
pageNum int - 1-based page number
startNum int -1 New page number
-1 : leave untouched

-2 : delete section from the given page. You cannot delete the first section, so pageNum must >=> 2 in this case.
name String or char* "--ignore--" section prefix, must be unique and not longer than 8 characters (but if you use more than 8 characters, all seems to work correctly anyway.)
"--ignore--" : leave untouched
marker String or char* "--ignore--" section marker
"--ignore--" : leave untouched
style int 0 Numbering format

-1 : leave untouched
0 : 1, 2, 3, 4, ...
1 : I, II, III, IV, ...
2 : i, ii, iii, iv, ...
3 : A, B, C, D, ...
4 : a, b, c, d, ...

5 : 01, 02, 03, ...
6 : 001, 002, 003, ...
7 : 0001, 0002, 0003, ...
8 : Fullwidth (?)
9 : Kanji
continuePrevious int -1 Continue counting of previous section?

-1 : leave untouched
0 : No, start counting here
1 : Yes
includeSectionPrefix int -1 -1 : leave untouched
0 : No
1 : Yes

Create some sections with different start pages and different numbering styles.

int main ()
{
    int		i;
    char	str [256];
    char	number [256];
    char	index [256];
page::set_number (0, 1, 12, "Anton ", "Anton markiert", 2); page::set_number (0, 4, -1, "Blümchen ", "Blümchen markiert", 1, 1, 1); page::set_number (0, 8, 6, "", "", 0, 0, 0);
/*   Expected result
  Anton xii   Anton xiii   Anton xiv   Blümchen XV   Blümchen XVI   Blümchen XVII   Blümchen XVIII   6 !page types changing!   7   8
*/

for (i = 1; i <= document::pages (0); i++) { page::get_str_by_index (str, 0, i, 1, 0, 1, 0); page::get_str_by_index (number, 0, i, 0, 1, 1, 1); page::get_str_by_index (index, 0, i, 0, 1, 2, 1); wlog ("", "# Page %d : '%s' (Number %s, Index %s)\n", i, str, number, index); }
return 0; }

Delete all sections and reset the documents page numbering style to default.

int main ()
{	
    int		i;
    char	str [256];
    char	nummer [256];
    char	index [256];
for (i = 2; i <= document::pages (0); i++) { page::set_number (0, i, -2); }
page::set_number (0, 1, 1, "", "", 0, 0, 0); for (i = 1; i <= document::pages (0); i++) { page::get_str_by_index (str, 0, i, 1, 0, 1, 0); page::get_str_by_index (nummer, 0, i, 0, 1, 1, 1); page::get_str_by_index (index, 0, i, 0, 1, 2, 1); wlog ("", "# Page %d : '%s' (Nummer %s, Index %s)\n", i, str, nummer, index); }
return 0; }

Version 2.1 R1789, 2. March 2010

priint:comet InDesign® Plug-Ins, comet_pdf

document::set_startpage

static int get_type(int pg = -1)

Ascertain the type (left, unisex, right side) of a specified page. The page is specified by means of its document-related 1-based page number. If the information is missing, the type of the current displayed page in InDesign® is ascertained. The function requires the import

#include "internal/types.h"

Name Type Default Description
Return int   Seitentyp
kUndefPage (-1) Page not found
kLeftPage (0) left page
kUnisexPage (1) Single sided page
kRightPage (2) right page
pg int - Page the type of which is to be ascertained. For the page number, the internal page number beginning with 1.
-1 : Page type in the upper window of the page displayed in InDesign®
#include "internal/types.h"

Version 1.2.1 (22 September 2005)

priint:comet InDesign® Plug-Ins, comet_pdf

grid::left
...
comet.CPage.getType

static int select(int pageNum)

Go to a page. The function only work on InDesign®, not on InDesign® Server. On InDesign® Server the error notForServerErr (1273) is returned. Page numbers beginning with 1, regardless of the start page number defined in the document.

Name Type Default Description
Return int   0 or ErrorCode
pageNum int - Page numberl
err_code		= page::select (pageNum);


priint:comet InDesign® Plug-Ins

page::get

static int create(
  int pages = 1,
  int at = -1,
  char* masterPage = "",
  float left = 0.0,
  float top = 0.0,
  float right = 0.0,
  float bottom = 0.0,
  int localize_items = false)

Create new document pages. The new pages can be inserted at user-defined locations in the document and are based on parent pages. If the parent pages contain frames with placeholders, these frames can be localised either automatically (localize_items != 0) or by a call of masteritems_load.

Name Type Default Description
Return int   0 or ErrorCode
pages int 1 Number of pages to be created
at int -1 At what location are the new pages to be inserted.
-1 : Append pages
masterPage String or char* "" Name of the parent page. If no parent page is specified, the default parent page will be used. Parent pages are specified in the format Prefix name, meaning "A-Parent page" for example.
left float 0.0 Specification of the page size. When left, top, right, bottom are 0.0, the standard page sizes will be used.
top float 0.0  
right float 0.0  
bottom float 0.0  
localize_items int 0 Are parent page frames with placeholders to be localised?

0 - do not localise
otherwise - localise

The Parameter localize_items is implemented from the Version 1.2.2 (Build 31 October 2005) implementiert.

priint:comet InDesign® Plug-Ins, comet_pdf

masteritems_load
comet.page.create

static int duplicate(
  ItemRef docRef = 0,
  int pageNum = 1,
  int reconstructCometData = 0)

Duplicate a document page. The new page is appended to the document.

Name Type Default Description
Return int   0 or ErrorCode
⇨ Within one document
docRef ItemRef 0 document reference

0 : current script document
pageNum int 1 page (1-based)
reconstructCometData int 0 0 : No, the new frames are not Comet grouped nor magneted
1 : Yes, create new groups and magnets like in the original frames
⇨ Append a page from another document, not supported by comet_pdf
docRef ItemRef - document reference

0 : current script document
fromPath char* oder String - Full path of the document in which the original page is located. If the document is not open, it is opened in the background and closed again after duplication.
pageNum int 1 page (1-based)
reconstructCometData int 0 0 : No, the new frames are not Comet grouped nor magneted
1 : Yes, create new groups and magnets like in the original frames

Duplicate the page of the current script frame and move the new page behind the current page. int main () { page::duplicate (0, page::get (gFrame)); page::move (0, document::pages (), page::get (gFrame));
return 0; }

v3.4 R5125, 21.01.2014
Parameter recreateCometGroups since v3.4 R5234, 13. Mar 2014
Duplicate from another document since v4.1.8 R27973, 19. Jan 2021

priint:comet InDesign® Plug-Ins, comet_pdf

page::move

static int move(
  ItemRef docRef,
  int pageNum,
  int behindPage)

Move a page of a document. The function will reshuffle the spreads.

Name Type Default Description
Return int   0 or ErrorCode
⇨ Within one document
docRef ItemRef - document reference

0 : current script document
pageNum int - page to move (1-based)
behindPage int - Move page behind this page (1-based)

0 : new first page
-1 : new last page
otherwise : 1-based page number
⇨ Remove page from another document and move it to the target document, not supported by comet_pdf
docRef ItemRef - document reference

0 : current script document
fromPath char* or String - Full path of the document from which the page is to be moved. If the document is not open, it will be opened in the background and saved and closed again after the page has been moved. If the document is already open, it is not saved.
pageNum int - Page of the original document to be moved (1-based). The page is removed from the original document and inserted into the target document.
behindPage int - Move page behind this page (1-based)

0 : new first page
-1 : new last page
otherwise : 1-based page number

Duplicate the page of the current script frame and move the new page behind the current page. int main () { page::duplicate (0, page::get (gFrame)); page::move (0, document::pages (), page::get (gFrame));
return 0; }

v3.4 R5125, 21.01.2014
Move from another document since v4.1.8 R27973, 19. Jan 2021

priint:comet InDesign® Plug-Ins

comet.CPage.setIndex

static int remove(int pgNum = 1, int reshuffle = 1)

Remove a page from the current document. Page numbers are 1-based. At least one page has to remain in the document.

Name Type Default Description
Return int   0 or ErrorCode
pgNum int 1 Number of page to remove (1-based)
reshuffle int 1 Reshuffle all following pages

0 : No
1 : Yes

Using comet_pdf pages are reshuffeled always!

Remove the 3rd page from the current document.

int main ()
{
    page::remove (3);
    return 0;
}

Version 1.3.3, P/R 60
Parameter exhaustive since v3.3.1 R3969, 2. Jul 2013

priint:comet InDesign® Plug-Ins

comet.CPage.remove

static int masteritems_load(int pg = -1, int CLASSID = 0)

Load the placeholders of the frames from the parent pages of a page.

The frames assumed from the respective parent pages of a document page are not automatically processed during the processing of the placeholders. In order that parent page elements can be processed as independent page contents they must first be localised. The localisation can take place manually in the document (Command-Shift-Click on the frame). When changing the associated (non-localised) frames of the parent page, only the non-overwritten frame properties from the parent page are assumed. If frames are the localised, they can be processed and changed like normal frames.

A call of the function masteritems_load localises all parent page frames connected with a placeholder > 0 of the specified page. The record ID of the linked product can be [0, 0, 0, ""] here. If the frame is localized, the placeholders are loaded in the frame.

Repeated calls of masteritems_load are permitted. The function recognised independently if a parent page frame is already localised. In this case the placeholders of the localisation are processed, without localising the frames.

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

-50 : function called for page 0 is not allowed
pg int -1 Which page is to be processed?

-1 : All pages
otherwise : 1-based page number

To load the parent items of the page of the current script frame you may use page::get (gFrame) here.
CLASSID int 0 CLASS number of the placeholder which is to be loaded.

0 - Ignore the CLASS number
otherwise - Only placeholders with this CLASS number will be loaded

Version 1.2.2 (31 October 2005)

priint:comet InDesign® Plug-Ins, comet_pdf

document::build_products
page::create
page::get

static int get_size(
  int pg,
  float* l,
  float* t,
  float* r,
  float* b,
  int marginRel = 0,
  ItemRef docRef = 0)

Get the page size in points.

Name Type Default Description
Return int   0 or ErrorCode
pg int - 1-based page number
l, t, r, b float* - output variables. All values are given in points
marginRel int 0 page size without margins? 0 : no, full page
otherwise : yes, without margins
docRef ItemRef - since v4.1.6, R26111 Which document should be queried??

0 : Current front document

version 1.3.5, R 236
Parameter docRef since v4.1.6, R26111

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

comet.CPage.getSize

static int set_size(
  ItemRef docRef,
  int page,
  float width,
  float height,
  int refPoint = 0)

Set the size of a page.

In page-based layouts such as those generated by InDesign® and comet_pdf, the size of the pages is a fundamental information and changing page sizes will lead to significant differences in the output.

The page::set_size function only changes the page size! Apart from a possible re-adjustment of the frames according to the given reference point no reorganization of the page contents will be made! This means in particular:

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document
0 : Current front document
page int - 1-based page number
width float - New width in points
height float - New height in points
refPoint int kRefPointTopLeft Reference point for resizing

kRefPointTopLeft (0)
kRefPointTopCenter(1)
kRefPointTopRight(2)
kRefPointLeftCenter(3)
kRefPointCenter(4)
kRefPointRightCenter(5)
kRefPointBottomLeft(6)
kRefPointBottomCenter(7)
kRefPointBottomRight(8)

InDesign and comet_pdf only!

InDesign und comet_pdf since v4.3 R34020, 1. Dez 2024

Illustrator, InDesign® Plug-Ins, comet_pdf

comet.CPage.setSize

static int get_margins(
  int pg,
  float* insideLeft,
  float* top,
  float* outsideRight,
  float* bottom,
  int facingRule = 0)

Get the page margins in points. Right and bottom margins are based on right/bottom page size

Name Type Default Description
Return int   0 or ErrorCode
pg int - 1-based page number
insideLeft float - returns the inside (for facing pages case) or left margin in points
top float - returns the top margin in points
outsideRight float - returns the outside (for facing pages case) or right margin in points
bottom float - returns the bottom margin in points
facingRule int 0 What to return on facing pages :

0 : inner, top, outer, bottom
1 : left, top, right, bottom

version 1.3.5, R 236
Parameter facingRule since v3.3 R3021, 29.05.2012

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CPage.getMargins

static int set_margins(
  int pg,
  float insideLeft,
  float top,
  float outsideRight,
  float bottom)

Set the margins of a page

Name Type Default Description
Return int   0 or ErrorCode
pg int - 1-based page number
insideLeft float - refers to new inside (for facing pages case) or left margin in points
top float - refers to new top margin in points
outsideRight float - refers to new outside (for facing pages case) or right margin in points
bottom float - refers to new bottom margin in points
facingRule int 0 To what do the new values refer?

0 : inner, top, outer, bottom
1 : left, top, right, bottom

version 1.3.5, R 236
Parameter facingRule since v3.3 R3021, 29.05.2012

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CPage.setMargins

static int count_columns(
  int pg,
  float* gutter = 0,
  int* direction = 0,
  int useMaster = 0)

Count the columns of a page.

Name Type Default Description
Return int   Number of columns of a page or 0 in case of some errors
pg int - 1-based page number
gutter float* 0 Gutter width in points
direction int* 0 Direction of coluns

0 : roman columns
1 : vertical columns
useMaster int 0 If you want to know the gutter and direction of the parent page, set it to 1.

DEPRECATED since v4.0.5 R14200, 8. Dec 2016 and InDesign® CC : Since InDesign® CC you cannot ask for the parent page columns anymore. The Parameter useMaster is therefore ignored and the current values from the page (possible inherited from the parent page) are returned always.
int main ()
{
    int			cols;
    float		gt;
    int			dir;
cols = frame::count_columns (gFrame, >); wlog ("", "Frame : %d columns, gutter %f\n", cols, gt);
cols = page::count_columns (page::get (gFrame), >, &dir); wlog ("", "Page %d : %d columns, gutter %f, direection %d\n", page::get (gFrame), cols, gt, dir);
return 0; }

Version 3.1 R2222, 7. Dez. 2010

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CPage.getColumnCount
comet.CPage.getColumnGutter

static char* get_masterpage(int pg)

Find the masterpage of a given page of the front document.

Name Type Default Description
Return char*   Parent page of the given page of the front document.

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.

pg int 1 1-based page number
char		m[500];
strcpy (m, page::get_masterpage (page::get ()));

Version 1.4.1 R423, 30. Jul 2007

priint:comet InDesign® Plug-Ins, comet_pdf

set_masterpage
comet.CPage.getMasterPage

static int set_masterpage(
  int pg,
  char* leftM,
  char* middleM = "",
  char* rightM = "",
  int resizeChoice = 1)

Change the parent mage of a given page of the front document.

Name Type Default Description
Return int   0 or ErrorCode
int pg 1 1-based page number
masterL char* - Prefix and name of an existing parent page ("A-Parent"). This value is used for left pages.
masterM char* - Prefix and name of an existing parent page ("A-Parent"). This value is used for inner pages.

"" : Use masterL

"" : Verwende masterL

Since CS5 the value is ignored.
masterR char* - Prefix and name of an existing parent page ("A-Parent"). This value is used for right pages.

"" : Use masterL

Since CS5 the value is ignored.
resizeChoice int 1 since CS5 Change page size according to the parent page?

0 : Yes, change page size if necessary
1 : No, keep current page size
2 : Ask user

Version 1.4.1 R423, 30. Jul 2007

Parameter resizeChoice since version 3.1 R1830, 14. April 2010

priint:comet InDesign® Plug-Ins, comet_pdf

get_masterpage
comet.CPage.getMasterPage

static int crop(
  ItemRef docRef,
  int page = 1,
  int keepMargins = 1)

Crop document pages to the bounding box of their frames. All given pages are resized to the bounding box of their frames. and moved to the upper left corner of the page (inside the margins).

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document ref, 0: current document
page int 1 Destination page

For versions prior CS5 the bounding boy of all frames of the given page are used as page size for all document pages. In addition, the frames of the given page are moved to upper left corner of the page (inside the margins).

Since CS5 document pages may have different sizes. All given pages are resized to the bounding box of their frames. and moved to the upper left corner of the page (inside the margins).

Attention:The page frames plus the page margins may by smaller than the parent page margins. In this case the parent page margins are set to (0, 0, 0, 0) automatically. All pages, using this parent page margins will lost their margins in this situation. Using page::set_margins you can set parent page independent margins.

Empty pages are not resized.

-1 : prior CS5 : first page
-1 : since CS5 : all pages
>= 1 : prior CS5 : use this page to find out the new page size (1-based)
>= 1 : since CS5 : this page only (1-based)
keepMargins int 1 Keep margins?

0 : Set margins to (0, 0, 0, 0)
1 : Leave local page margins untouched

Version 2.1 R1089, 18.12.2008
page and keepMargins since v3.3 R3021, 30. Mai 2012

priint:comet InDesign® Plug-Ins, comet_pdf

static int get_info(
  ItemRef docRef,
  int pg,
  char* attribute,
  int* value)

The function determines information about the Page Template linked to a given page.

Please note that the results of the function are determined from the current document page. To query the definition of a Page Template in the data pool, please use the functionn page::templates::get_info. To determine the elements of a Page Template, please use the functions page::templates::count_elements and page::templates::get_element_info_by~.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Valid document reference
0 : current front document
pg int - page number (1-based)
-1 : current front page, docRef is unused in this case

Using InDesign® Server or comet_pdf the current front page is undefined!

attribute String or char* - Information to set. See table page information. Information names are case-sensitive!
value int* | String or char* | float* - Information catcher, must match the attribute, see above!

Version 3.0 R911, 15. August 2008

priint:comet InDesign® Plug-Ins, comet_pdf

set_info
page::templates::get_info

static int set_info(
  ItemRef docRef,
  int pg,
  char* attribute,
  int value,
  int applyMaster = 0)

Since Comet 3.0. Set information about a document page.

In function calls, make sure that the data type of the value always matches the attribute.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Valid document reference
0 : current front document
pg int - page number (1-based)

Using InDesign® Server or comet_pdf the current front page is undefined!

attribute String or char* - What information do you want to change? See tabler Page Information. "id" and "ids" change all page template information according to the definitions of the current data pool.

Element properties cannot be changed with this function!
value int | String or char* | float - New value
applyMaster int 0 For the attributes "id"  and "ids"  only! Should a possible given parent page in the page template be applied automatically too?

0 : No, leave parent page untouched
1 : Yes, if a parent page given in the page template exists

No other indirect document changes are made from other attributes!

Version 3.0 R911, 15. August 2008
Parameter applyMaster since v4.2 R32161, 19. Jan 2023

priint:comet InDesign® Plug-Ins, comet_pdf

get_info

static int get_spread(
  ItemRef docRef,
  int pg,
  int* indexInSpread = 0)

Get the spread index of a page.

Name Type Default Description
Return int   Spreadindex or -1 on error
docRef ItemRef - document
0 : current script document
pg int - 1-based page index
indexInSpread int* 0 (on return) 0-based index of page in spread

0 : ignore
int main ()
{
    int        pg            = page::get (gFrame);
    int        indexInSpread;
    int        spread        = page::get_spread (0, pg, &indexInSpread);
    ItemRef    pageRef       = item::alloc ();
    ItemRef    spreadRef     = item::alloc ();
document::get_pageref (pageRef, 0, pg); document::get_spreadref (spreadRef, 0, spread);
wlog ("", "Spread %d (%d), Seite %d (%d), %d. page in Spread\n",   spread, item::getint (spreadRef),   pg, item::getint (pageRef), indexInSpread);
return 0; }

v3.3 R3500, 08.03.2012

priint:comet InDesign® Plug-Ins, comet_pdf

page::get_spread
comet.CPage.getIndexInSpread

static int get_free_rects(
  RectList R,
  ItemRef docRef,
  int pg,
  int flags = 0,
  float treshold = 1.2,
  Rect outsets = 0,
  int fn_best_rect = 0)

Determine a list of rectangles with which the free area of a page can be completely covered. To determine the free areas, the entire page is divided into so-called tiles in a first step. The grid for the tiles is formed by the outer edges of all the frames and delimited by the page margin resp. edges . Here you can see a rather simple case with tow frames (with blue border) and its free tiles (here in green):

In a second step, all possible greatest rectangulare candidates are determined from the free tiles. The candidates can partially overlap each other but never overlap any already occupied tile. Here is a screenshot of the first pass of the above example. Darker green areas are overlaps of possible candidates:

From the list of candidates, the 'best' rectangle is selected in a third step. This frame is added to the result list and the tiles involved are marked as occupied. Steps two and three are repeated until no area of the page is unoccupied.

Please note that the result (except for the empty page) is not unique of course. However, you can affect the result with the parameter treshold and/or a custom function fn_best_rect for the rectangle comparisons.

With the threshold values 1.2 (default), 1.5 and 2.0 the following different results are obtained:

The comparison function bestRect from the example below only checks the aspect ratios. Here are the two solutions, if the widest resp. the highest frame is always preferred:

Name Type Default Description
Return int   0 or ErrorCode
R RectList - Allocated RectList for the results
docRef ItemRef - Valid document reference
0 : Current front document
pg int - Page number (1-based)
flags int 0 Additional information

1 : Restrict page to margins
2 : Calculate list of the individual tiles only
4 : Calculate list of candidates only
8 : Evaluate text and tables as individual areas
16 : Calculate occupied areas only
outsets Rect 0 Size adjustment of the occupied individual surfaces
0 : No Size Adjustment
treshold float 1.2 Treshold value ≥ 1.0. For values smaller than 1.0, the aspect ratio is ignored.

When determining the next best rectangle from the possible candidates the sizes and aspect ratios of the rectangles are compared: Up to a size ratio 1 : treshold, the larger rectangle is preferred. If the size ratio is smaller, the rectangle with the better aspect ratio (closer to 1.0) will be used. So the larger you make the treshold, the narrower (or flatter) your results tend to become.
fn_best_rect int 0 Function of type
int fn (RectList candidates)}
defined in the script to determine the best rectangle from the current list of possible candidates. The candidates list is pre-sorted and contains as the first element is the internally calculated best rectangle. If a different rectangle is to be used the function must return the (0-based) list index of the preferred rectangle.

If such a function is used, the whole script must be implemented in cScript and no global variables of the script may be used in the function.

#pragma plain
#include "internal/types.h" #include "internal/text.h"
// *****************************************************************************
float kMinHeight = 65.0; float kMinWidth = 40.0; float kShrinkTop = 3.0; float kShrinkLeft = 3.0;
// *****************************************************************************
// This function decides which is the best rectangle in the current step. // The function is optional. // Unlike the default always take the largest rectangle (and ignore the proportions). // int bestRect (RectList R) { int result = 0; Rect r; float area, area1; int i;
// Init // r = rectlist::first (R); area = rect::width (r) * rect::height (r);
// Walk through the remaining rects and look for // a bigger one. // for (i = 1; i < rectlist::length (R); i++) { r = rectlist::get (R, i); area1 = rect::width (r) * rect::height (r); if (area1 > area) result = i; }
// We have to return the INDEX of the biggest rect // return result; }
// *****************************************************************************
// Main Function // int main () { RectList R = rectlist::alloc (); ItemRef fr = item::alloc (); String str = string::alloc (); int PG = document::pages (); float marginL, marginT, left, top; int pg; Rect r; int result; int i, flags;
if (gRun > 1) return 0;
flags = 1 + 8; // Margin relative + Text aware if (system::shiftkey ()) flags += 2; // Tiles only else if (system::cmdkey ()) flags += 4; // Candidates only else if (system::controlkey ()) flags += 16; // Occupied areas only
if (PG > 3) progress::start ("Find Free Places on Document Pages", PG);
for (pg = 1; pg <= document::pages (); pg++) { if (PG > 3) { string::set (str, "Page %d / %d", pg, PG); progress::step (str); progress::unit ("Calculating ..."); } result = page::get_free_rects (   R,   0, // docref   pg, // 1-based page   flags,   0, // text tresholds   1.0, // treshold   bestRect); // Optional : Chose the biggest rect always if (result != 0) { showmessage ("Error %d", result); return 0; }
// From the results I create document frames here. Small frames are ignored. // Of course, this step is not necessary. It serves only for visualization. // if (PG > 3) { progress::unit ("Creating Frames ..."); } layer::add ("RRR", ""); // Use an own layer for the new frames if (flags & 0x0010) // Do not shrink the frames in case of 'occupied' only { kShrinkTop = 0.0; kShrinkLeft = 0.0; }
page::get_margins (pg, &marginL, &marginT, 0, 0);
i = 0; // It's a counter for the frames only for (r = rectlist::first (R); r; r = rectlist::next (R)) { if ((flags & 0x0010) || rect::width (r) >= kMinWidth && rect::height (r) >= kMinHeight) { // Create and configure the frame // left = rect::left (r); top = rect::top (r); if (left > marginL + 10.0) left += kShrinkLeft; if (top > marginT + 10.0) top += kShrinkTop;
frame::create2 (fr, kRectangle, left, top, rect::right (r), rect::bottom (r), pg); frame::color_rgb (fr, 0, 128, 255); frame::set_corner (fr, 0, 1, 11.0); frame::set_blending (fr, kBlendingFill, 25.0); frame::move_to_layer (fr, "RRR");
// Set a counter and the frame size into the frame // string::set (str, "%%!TT<cSize:32.0>%d<cSize:8.0.0> : %.0f pt<cPosition:Superscript>2<cPosition:>", ++i, rect::width (r) * rect::height (r)); frame::replace (fr, str); } }
rectlist::clear (R); }
if (PG > 3) progress::stop (); item::release (fr); rectlist::release (R);
return 0; }

v4.2 R31175, 11. Jul 2022

priint:comet InDesign® Plug-Ins, comet_pdf

static int templates::get_info(
  int id,
  char* attribute,
  int* value)

Determine the properties of a Page Template given in the current data pool.

Please note that the results of the function are determined from the definition of the Page Template in the data pool. To determine the properties of the Page Template linked to a given document page, please use the function page::get_info.

Pages and Page Templates can contain the following information. All attribute names are case sensitive. In function calls, please make sure that the data type of the value always matches the attribute.
Attribute Type Defined for Description
active int page::get_info
page::set_info
page::templates::get_info
0 | 1
id int On setting, the page type matching template use used automatically.
ids int Like id, but all following pages are changed in respect to successor of the use template too.
name char*
pagetype int 0 : any, 1 : left, 2 : right
barrier int ID of script after apply page template to page
successor int
masterpages char* comma separated list of parent page names
autooposite int 0 | 1
autosuccessor int 0 | 1
oposite int
origin int since v4.1.6 R26001 UID of the page in the document template. The information is only required in Master-Variant Syncs.
label char* page::templates::get_info
docname char*
owner int ID of of template file containig this page template

Name Type Default Description
Return int   0 or ErrorCode
id int - id of page template
attribute String or char* - Information type. See table page information. Attribute names are case-sensitive!
value int | String or char* | float - Information catcher must match the slot, see above!

Version 3.0 R911, 15. August 2008

priint:comet InDesign® Plug-Ins, comet_pdf

get_info
set_info

static int templates::count_elements(int id)

Count the elements of a Page Template stored in the current data pool.

Name Type Default Description
Return int   number of elements stored in a page template of the current data pool.

0 : Error or template not found
id int - ID of page template

Version 3.0 R911, 15. August 2008

priint:comet InDesign® Plug-Ins, comet_pdf

static int templates::get_element_info_by_sequ(
  int id,
  int sequ,
  char* attribute,
  int* value)

Determine the properties of an Element of a Page Template. The Element is defined by its sequence number.

Please note that information about the elements of a Page Template are not saved in the document. This information can only be determined from the data pool. You can obtain the Page Template linked to a document page using the function page::get_info with the attribute "id".

The following (case-sensitive) attributes are supported:
Attribute Tyep Description
Name char*
UID int
Active int
Sequ int
Type int
AutoLink int
VerticalJust int
MinimumVJ int
StylesVJ int
MinimumVJEnabled int
StylesVJEnabled int
HasMoreObjects int
BuildDirection int
MinDistX float
MinDistY float
JustificationEnabled int
Justification int
JustificationScript int
BBox.Left float
BBox.Top float
BBox.Right float
BBox.Bottom float

Name Type Default Description
Return int   0 or ErrorCode
id int - id of page template
sequ int - sequence number of element (1-based)
attribute String or char* - Information type. See table element information. Attribute names are case-sensitive!
value int | String or char* | float - result catcher, see table element information.

Version 3.0 R911, 15. August 2008

priint:comet InDesign® Plug-Ins, comet_pdf

get_element_info_by_index

static int templates::get_element_info_by_index(
  int id,
  int idx,
  char* attribute,
  int* value)

Determine the properties of an Element of a Page Template. The Element is defined by its index inside the Page Templates element list.

Please note that information about the elements of a Page Template are not saved in the document. This information can only be determined from the data pool. You can obtain the Page Template linked to a document page using the function page::get_info with the attribute "id".

Name Type Default Description
Return int   0 or ErrorCode
id int - id of page template
idx int - index of element (0-based)
attribute String or char* - Information type. See table element information. Attribute names are case-sensitive!
value int | String or char* | float - result catcher, see table element information.

Version 3.0 R911, 15. August 2008

priint:comet InDesign® Plug-Ins, comet_pdf

get_element_info_by_index

static int guides::add(
  ItemRef docRef,
  int pageNum,
  int is_horizontal,
  float position,
  int for_spread = 0,
  int color_index = 6,
  float threshold = 0.05)

Create or change a guide line.

If a guide line already exists at the given position with same direction (vertical or horizontal, see guides::get_direction) and of the same scope (page or spread, see guides::get_owner), only the color (color_index) and the threshold (threshold) are changed. Otherwise a new guide line will be created with the given settings.

Please note that the direction, scope and position of a guide line cannot be changed. In these cases you create a new guide line with the desired settings and delete the old guide line.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document reference
0 : current front document
pageNum int - 1-based page number in document

The page number is used to determine the spread on which the page is located. From this spread all guide lines are checked, whether only the color (color_index) and threshold (threshold) must be changed (see above), or whether a new guide line must be created.
is_horizontal int - 0 : vertical
1 : horizontal
position float - Indicates the position of the guide line in points relative to the upper left corner of the given page.
for_spread int 0 0 : page
1 : spread
color_index int 6 Index of a GUI color defined in InDesign® (so called i>stock color). We do not provide a complete list here. To determine the desired index, manually create a guide once and right-click it to open the settings for the guide line. In the color setting you can get the desired index easily by counting the entries. The first color has the index 0.
threshold float 0.05 Guide lines can be automatically hidden if the zoom factor of the page display is sufficiently small. Enter the percentage value of the zoom factor from which the help line is to become visible, 1.0 corresponds to 100% (and 0.05 is 5%).

Erzeuge zwei Hilfslinien auf der ersten Dokumentseite.

int main ()
{
    page::guides::add (0, 1, 0, 120.0, 0, 30); // vertical
    page::guides::add (0, 1, 1, 120.0, 0, 25); // horiz
return 0; }

Version 4.1.6 R24346, 20. Jun 2019

priint:comet InDesign® Plug-Ins

guides::get
guides::remove

static int guides::get(
  ItemRef docRef,
  int pageNum,
  ItemList result_list)

Get a list of all guilde lines of the spread of a given page.

In comet_pdf und Illustrator® ist die Funktion leer definiert und gibt den Wert -1199 zurück.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document reference
0 : current front document
pageNum int - 1-based page number in document

The page number is used to determine the spread on which the page is located. From this spread, all guide lines are determined.
result_list ItemList - Allocated ItemList for the results, see itemlist::alloc. After successful return of the function the list contains all guide lines of the spread on which the given page is located.

Change the horizontal guide line at 100pt of the current page to a vertical guide line.

int main ()
{
    int 		pg 			= page::get (gFrame);
    ItemList	li 			= itemlist::alloc ();
    int 		i;
    ItemRef 	guideRef 	= item::alloc ();
    ItemRef 	ownerRef 	= item::alloc ();
page::guides::get (0, pg, li);
for (i = 0; i < itemlist::length (li); i++) { itemlist::get (li, guideRef, i);
wlog ("", "Guide %d :\n\tUID\n", i+1, item::getint (guideRef)); wlog ("", "\thorizontal\t%d\n", page::guides::get_direction (guideRef)); wlog ("", "\towner\t\t%d (UID %d)\n", page::guides::get_owner (guideRef, ownerRef), item::getint (ownerRef)); wlog ("", "\tposition\t\t%f\n", page::guides::get_position (guideRef)); wlog ("", "\tthreshold\t%f\n", page::guides::get_threshold (guideRef)); wlog ("", "\tcolor\t\t%d\n", page::guides::get_colorindex (guideRef));
if ( page::guides::get_owner (guideRef, 0) == pg   && page::guides::get_direction (guideRef) == 1   && page::guides::get_position (guideRef) == 100.0) { wlog ("", "\tCHANGED!!!\n"); page::guides::add (0, pg, 0, 100.0, 0,   page::guides::get_colorindex (guideRef),   page::guides::get_threshold (guideRef)); page::guides::remove (guideRef); } }
return 0; }

Version 4.1.6 R24346, 20. Jun 2019

priint:comet InDesign® Plug-Ins

static int guides::remove(ItemRef guideRef)

Remove a guide line.

In comet_pdf und Illustrator® ist die Funktion leer definiert und gibt den Wert -1199 zurück.

Name Type Default Description
Return int   0 or ErrorCode
guideRef ItemRef - Valid reference of a guide line. References to guide lines can be obtained using the function guides::get.

Version 4.1.6 R24346, 20. Jun 2019

priint:comet InDesign® Plug-Ins

guides::get

static int guides::get_direction(ItemRef guideRef)

Is the guide line vertical or horizontal?

In comet_pdf and Illustrator® the function in defined empty and returns -1 always.

Name Type Default Description
Return int   0 : vertical
1 : horizontal
-1 : Error
guideRef ItemRef - Valid reference of a guide line. References to guide lines can be obtained using the function guides::get.

Version 4.1.6 R24346, 20. Jun 2019

priint:comet InDesign® Plug-Ins

guides::get

static int guides::get_owner(ItemRef guideRef, ItemRef* resultRef = 0)

Determine the type of a guilde line. Guide lines can be defined for a single page or for the entire spread.

In comet_pdf and Illustrator® the function in defined empty and returns -1 always.

Name Type Default Description
Return int   Type of guide ine

0 : Spread
> 0 1-based page number
< 0 : Error
guideRef ItemRef - Valid reference of a guide line. References to guide lines can be obtained using the function guides::get.
resultRef ItemRef 0 If the Parameter is missing or 0, it is ignored.

Otherwise the Parameter must contain an allocated ItemRef (see item::alloc) and contains a reference to the page or spread if the function is executed successfully.

Version 4.1.6 R24346, 20. Jun 2019

priint:comet InDesign® Plug-Ins

guides::get

static float guides::get_position(ItemRef guideRef)

Determine the position of a guide line.

In comet_pdf and Illustrator® the function in defined empty and returns -1000001.0 always.

Name Type Default Description
Return float   Position of an guide line in points relative to the upper left corner of the page resp. spread.

< -1000000.0 : Error while getting the position
guideRef ItemRef - Valid reference of a guide line. References to guide lines can be obtained using the function guides::get.

Version 4.1.6 R24346, 20. Jun 2019

priint:comet InDesign® Plug-Ins

guides::get

static float guides::get_threshold(ItemRef guideRef)

Determine the threshold value of the page zoom from which a guide line is to be shown. The line is not shown until a zoom factor of the specified size. If the zoom factor is smaller, it is automatically faded out.

In comet_pdf and Illustrator® the function in defined empty and returns -1.0 always.

Name Type Default Description
Return int   Zoom factor of page display from which the line is to become visible. 1.0 corresponds to 100%.

< 0.0 : Error while getting the threshold
guideRef ItemRef - Valid reference of a guide line. References to guide lines can be obtained using the function guides::get.

Version 4.1.6 R24346, 20. Jun 2019

priint:comet InDesign® Plug-Ins

guides::get

static int guides::get_colorindex(ItemRef guideRef)

Determine the color index of a guide line. The color index is the index of a built-in list of colors in InDesign® for layers, frame edges, XML elements, guilde lines and other GUI objects.

In comet_pdf and Illustrator® the function in defined empty and returns -1 always.

Name Type Default Description
Return int   0-based stock color index of InDesign®

-1 : Error while getting the color index
guideRef ItemRef - Valid reference of a guide line. References to guide lines can be obtained using the function guides::get.

Version 4.1.6 R24346, 20. Jun 2019

priint:comet InDesign® Plug-Ins

guides::get

Author
Paul Seidel
Version
06.02.2024, 10:21 Uhr
See Also
document::pages
item

Alphabetic index HTML hierarchy of classes or Java