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 pageitemRef 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 pageint pg = page::get ([itemRef]);
- Since
- Parameter queryNearest since v3.3 R3116, 10. Aug. 2012
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator
- See Also
- 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 founddocRef ItemRef - Document reference
0 : Current front documentpnum 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)- Since
- v4.1.6, 28. Sep 2019
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- page::get
page::get_str
itemcomet.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]]]]);
- Since
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator
- See Also
- page::get
get_str_by_index
itemcomet.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 documentpageNum 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);- Since
- Version 2.1 R1789, 2. March 2010
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator
- See Also
- 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 documentpageNum 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 untouchedmarker String or char* "--ignore--" section marker
"--ignore--" : leave untouchedstyle 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 : KanjicontinuePrevious int -1 Continue counting of previous section?
-1 : leave untouched
0 : No, start counting here
1 : YesincludeSectionPrefix int -1 -1 : leave untouched
0 : No
1 : YesCreate 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; }- Since
- Version 2.1 R1789, 2. March 2010
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- 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®- Preconditions
- #include "internal/types.h"
- Since
- Version 1.2.1 (22 September 2005)
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- 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);
- Since
- Available
- priint:comet InDesign® Plug-Ins
- See Also
- 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. Here you will find a description of how to configure parent page frames (aka 'master page items').
-
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 pagesmasterPage 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- Since
- The Parameter localize_items is implemented from the Version 1.2.2 (Build 31 October 2005) implementiert.
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- masteritems_loadcomet.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 documentpageNum 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 documentfromPath 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 framesDuplicate 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; }- Since
- 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 - Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- 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 documentpageNum 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 documentfromPath 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 numberDuplicate 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; }- Since
- v3.4 R5125, 21.01.2014
Move from another document since v4.1.8 R27973, 19. Jan 2021 - Available
- priint:comet InDesign® Plug-Ins
- See Also
- 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 : YesUsing comet_pdf pages are reshuffeled always!
Remove the 3rd page from the current document.
int main () { page::remove (3); return 0; }- Since
- Version 1.3.3, P/R 60
Parameter exhaustive since v3.3.1 R3969, 2. Jul 2013 - Available
- priint:comet InDesign® Plug-Ins
- See Also
- 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.
Here you will find a description of how to configure parent page frames (aka 'master page items').
-
Name Type Default Description Return int 0 or ErrorCode
-50 : function called for page 0 is not allowedpg 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- Since
- Version 1.2.2 (31 October 2005)
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- document::build_products
page::create
page::getcomet.CPage.loadMasterItems
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 marginsdocRef ItemRef - since v4.1.6, R26111 Which document should be queried??
0 : Current front document- Since
- version 1.3.5, R 236
Parameter docRef since v4.1.6, R26111 - Available
- priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator
- See Also
- 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:
-
Frame assignments to spreads (InDesign®) or pages (comet_pdf) remain unchanged.
If frames fall geometrically from the spread or the page, they become invisible in the exported PDF.
There is no customization of the parent pages and their elements!
Any page templates remain unchanged.
InDesign® partially realizes changes to the page size by shifting the page coordinate system
of the page. This can also change the frame coordinates.
-
Name Type Default Description Return int 0 or ErrorCode docRef ItemRef - Document
0 : Current front documentpage 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!- Since
- InDesign und comet_pdf since v4.3 R34020, 1. Dez 2024
- Available
- Illustrator, InDesign® Plug-Ins, comet_pdf
- See Also
- 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- Since
- version 1.3.5, R 236
Parameter facingRule since v3.3 R3021, 29.05.2012 - Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- 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- Since
- version 1.3.5, R 236
Parameter facingRule since v3.3 R3021, 29.05.2012 - Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- 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 columnsuseMaster 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; }- Since
- Version 3.1 R2222, 7. Dez. 2010
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- comet.CPage.getColumnCountcomet.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 ()));- Since
- Version 1.4.1 R423, 30. Jul 2007
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- set_masterpagecomet.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- Since
- Version 1.4.1 R423, 30. Jul 2007
Parameter resizeChoice since version 3.1 R1830, 14. April 2010 - Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- get_masterpagecomet.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- Since
- Version 2.1 R1089, 18.12.2008
page and keepMargins since v3.3 R3021, 30. Mai 2012 - Available
- 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 documentpg 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 get. See table page information. Information names are case-sensitive! value int* | String or char* | float* - Result value, must match the attribute, see above! - Since
- Version 3.0 R911, 15. August 2008
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- 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 documentpg 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!- Since
- Version 3.0 R911, 15. August 2008
Parameter applyMaster since v4.2 R32161, 19. Jan 2023 - Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- 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 documentpg int - 1-based page index indexInSpread int* 0 (on return) 0-based index of page in spread
0 : ignoreint 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; }- Since
- v3.3 R3500, 08.03.2012
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- page::get_spreadcomet.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 documentpg 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 onlyoutsets Rect 0 Size adjustment of the occupied individual surfaces
0 : No Size Adjustmenttreshold 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; }- Since
- v4.2 R31175, 11. Jul 2022
- Available
- 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* - Result value must match the slot, see above! - Since
- Version 3.0 R911, 15. August 2008
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- get_info
set_infocomet.pagetemplate.getInfo
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 foundid int - ID of page template - Since
- Version 3.0 R911, 15. August 2008
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- comet.pagetemplate.getElementCount
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. - Since
- Version 3.0 R911, 15. August 2008
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- get_element_info_by_index
comet.pagetemplate.getElementInfo
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. - Since
- Version 3.0 R911, 15. August 2008
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- get_element_info_by_index
comet.pagetemplate.getElementInfo
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 documentpageNum 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 : horizontalposition 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 : spreadcolor_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; }- Since
- Version 4.1.6 R24346, 20. Jun 2019
- Available
- priint:comet InDesign® Plug-Ins
- See Also
- 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 documentpageNum 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; }- Since
- Version 4.1.6 R24346, 20. Jun 2019
- Available
- 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. - Since
- Version 4.1.6 R24346, 20. Jun 2019
- Available
- priint:comet InDesign® Plug-Ins
- See Also
- 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 : ErrorguideRef ItemRef - Valid reference of a guide line. References to guide lines can be obtained using the function guides::get. - Since
- Version 4.1.6 R24346, 20. Jun 2019
- Available
- priint:comet InDesign® Plug-Ins
- See Also
- 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 : ErrorguideRef 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.- Since
- Version 4.1.6 R24346, 20. Jun 2019
- Available
- priint:comet InDesign® Plug-Ins
- See Also
- 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 positionguideRef ItemRef - Valid reference of a guide line. References to guide lines can be obtained using the function guides::get. - Since
- Version 4.1.6 R24346, 20. Jun 2019
- Available
- priint:comet InDesign® Plug-Ins
- See Also
- 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 thresholdguideRef ItemRef - Valid reference of a guide line. References to guide lines can be obtained using the function guides::get. - Since
- Version 4.1.6 R24346, 20. Jun 2019
- Available
- priint:comet InDesign® Plug-Ins
- See Also
- 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 indexguideRef ItemRef - Valid reference of a guide line. References to guide lines can be obtained using the function guides::get. - Since
- Version 4.1.6 R24346, 20. Jun 2019
- Available
- priint:comet InDesign® Plug-Ins
- See Also
- guides::get