static ItemRef item::alloc(ItemRef org = 0)
Reserve memory capacity for an InDesign® object. The created ItemRef is thereby not yet connected with an InDesign® object. With alloc created ItemRefs these must be deleted again using item::release.
Please note the difference between the address of an ItemRef object and its UID: The address is the position of the ItemRef object in the memory. You can obtain such an address (but not yet an UID) with item::alloc, gFrame already has one. The UID, on the other hand, is (together with some other data) located at the address and InDesign® can derive the referenced object from this number.
-
Name Type Default Description Return ItemRef New created empty reference to an InDesign® object org ItemRef 0 original
0 : create a new empty ItemRef object
otherwise : make a copy of org Only the reference values are duplicated, not the refered objects itself!ItemRef frameRef = item::alloc ();
- Since
- org since version 1.3.4 (P/R 74)
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator®
static ItemRef item::assign(ItemRef dest, ItemRef src)
Copy on ItemRef to another. The value of src is copied into dest Of course, only the reference is copied here, not the referenced InDesign® object itself.
Please note the difference between the address of an ItemRef object and its UID: The address is the position of the ItemRef object in the memory. You can obtain such an address (but not yet an UID) with item::alloc, gFrame already has one. The UID, on the other hand, is (together with some other data) located at the address and InDesign® can derive the referenced object from this number.
-
Name Type Default Description Return ItemRef dest or 0 on error dest ItemRef - destination src ItemRef - original - Since
- Version 1.3.4 (P/R 74)
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator®
static int item::define(
ItemRef dest,
ItemRef srcDB,
int UID,
int checkIfExists = 1)
Define a reference to a document object.
Please note the difference between the address of an ItemRef object and its UID: The address is the position of the ItemRef object in the memory. You can obtain such an address (but not yet an UID) with item::alloc. The UID, on the other hand, is (together with some other data) located at the address and InDesign® can derive the referenced object from that information.
[since v4.3 R34250, 2. Feb 2024] If span[src]{dest} is equal to gDocument, the current document of the script is automatically adapted. In this case uid must have the value 1! Below you will find an example.
-
Name Type Default Description Return int 0 or ErrorCode. dest ItemRef - Destination reference srcDB ItemRef - Enter any (but a valid) object of the document in which your target object is located, gFrame is a good idea for example.
0 : Try to determine the document via the script environment:-
Current frame (gFrame)
Current textmodel
Current document
uid int - New object id checkIfExists int 1 Before defing the item, check whether an object with given UID exists.
1 : Yes, please check
0 : No, define anywayCheck a range of document UIDs.
int main () { int i; ItemRef ref = item::alloc ();
for (i = 200; i < 301; i++) { item::define (ref, gFrame, i); wlog ("", "# UID %d : %d, 0x%X'\n", i, item::exists (ref), item::get_class (ref)); }
return 0; }The UID 1 always points to the document. The examples creates an ItemRef to the document of the current frame an shows the documents name.
int main () { ItemRef docRef = item::alloc (); char docName [4000];
item::define (docRef, gFrame, 1); document::name (docName, docRef); showmessage ("%s", docName);
return 0; }Adapt gDocument to the current front document.
int front_doc_changed () { ItemRef docRef = document::get_front ();
item::define (gDocument, docRef, 1); item::release (docRef);
return 0; }- Since
- v3.3 R2489, 06.06.2011 Parameter checkIfExists since v4.1.6 R26001, 1. Oct 2019
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- defined
exists
get_class
comet.CDocument.getFrame
static int item::release(ItemRef itm)
The reserved memory of an object reference is again released. The target object of the reference remains unaffected by this action.
-
Name Type Default Description itm ItemRef - Reference to be released ItemRef frameRef = item::alloc (); : item::release (frameRef);
- Since
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator®
static int item::fitframe(
ItemRef ref,
int refPoint = 0,
float* width = 0,
float* height = 0)
Fit the frame, in which a reference is displayed, to its contents. In the optional parameters width and height, the new size of the frame can be requested.
-
Name Type Default Description Return int 0 or ErrorCode ref ItemRef - Reference to a document frame refPoint int kRefPointTopLeft Which corner of the origin frame should be pinned when scaling? Please note, that text frames are changed only in their height and that inline frames are always held at the bottom right corner.
kRefPointTopLeft
kRefPointTopCenter
kRefPointTopRight
kRefPointLeftCenter
kRefPointCenter
kRefPointRightCenter
kRefPointBottomLeft
kRefPointBottomCenter
kRefPointBottomRight
To fit frames to the contained image, use the frame::fit_image function with method 3.width float* 0 New width of the frame, Return value height float* 0 New height of the frame, Return value - Preconditions
- #include "internal/types.h"
- Since
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- frame::fit
frame::fit_better
frame::fit_imagecomet.CFrame.fit
ItemRef frame = item::alloc (); document::find_frame (frame, 1, 1, 3, 4);
if (!item::defined (frame)) { item::release (frame); showmessage ("Frame not found"); return 1; } item::fitframe (frame); item::release (frame);
static int item::defined(ItemRef ref)
Does the reference indicate a valid object?
ItemRefs can point to different objects like frames, tables, documents, ... . A call to defined only anwsers the question, whether the reference points to any object. You can not be sure, that is object is a frame, or a doc, or something else. Anyway, for the most reasons, htis information is enough. To check, whether the ref is a valid frame, table, ... , use one of the corresponding is_valid methods.
-
Name Type Default Description Return int != 0 the object is defined, == 0 no object ref ItemRef - Reference to a document frame ItemRef frame = item::alloc (); document::find_frame (frame, 1, 1, 3, 4);
if (!frame::is_valid (frame)) { item::release (frame); showmessage ("Frame not found"); return 1; } item::fitframe (frame); item::release (frame);- Since
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator®
- See Also
- frame::is_valid
table::is_valid
bookmark::is_valid
document::is_valid
hyerlink::is_valid
static int item::getint(ItemRef ref)
UID of the reference. Information on UIDs can be found here.
Please note the difference between the address of an ItemRef object and its UID: The address is the position of the ItemRef object in the memory. You can obtain such an address (but not yet an UID) with item::alloc, gFrame already has one. The UID, on the other hand, is (together with some other data) located at the address and InDesign® can derive the referenced object from this number.
-
Name Type Default Description Return int Value of the referenz ref ItemRef - documet reference - Since
- Version 1.4 R334 (13. April 2007)
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
- See Also
- comet.CFrame.getUID
static int item::exists(ItemRef ref)
Does the reference indicate an existing object?
ItemRefs can point to different objects like frames, tables, documents, ... . A call to defined only anwsers the question, whether the reference points to any object. You can not be sure, that is object is a frame, or a doc, or something else. Anyway, for the most reasons, htis information is enough. To check, whether the ref is a valid frame, table, ... , use one of the corresponding is_valid methods.
-
Name Type Default Description Return int 0 : No
1 : Yes, the object existsref ItemRef - reference Check a range of document UIDs.
int main () { int i; ItemRef ref = item::alloc ();
for (i = 200; i < 301; i++) { item::define (ref, gFrame, i); wlog ("", "# UID %d : %d, 0x%X'\n", i, item::exists (ref), item::get_class (ref)); }
return 0; }- Since
- v3.3 R2489, 06.06.2011
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf
static int item::get_class(ItemRef ref)
Get the class of an existing document object. Here's a small collection of IDs and their names.
| ClassID | Name |
| 0x0E01 | kDocBoss |
| 0x0501 | kSpreadBoss |
| 0x050F | kPageBoss |
| 0x1401 | kMasterPagesBoss |
| 0x0302 | kDocumentLayerBoss |
| 0x0301 | kSpreadLayerBoss |
| 0x0201 | kTextStoryBoss |
| 0x2C0f | kPageItemBoss |
| 0x0263 | kMultiColumnItemBoss |
| 0x0227 | kFrameItemBoss |
| 0x2C10 | kDrawablePageItemBoss |
| 0x6201 | kSplineItemBoss - All generic document frames except inline frames have this class. |
| 0x1701 | kImageBaseItem |
| 0x1702 | kImageItem |
| 0x2501 | kPlacedPDFItemBoss |
| 0x660B | kEPSTextItemBoss |
| 0x6611 | kDisplayListPageItemBoss |
| 0x6601 | kEPSItem |
| 0x6602 | kPICTItem |
| 0x6603 | kWMFItem |
| 0x660f | kDCSItemBoss |
| 0x0401 | kGroupItemBoss - These are InDesign® groups. |
| 0xB320 | kTOPSplineItemBoss - Text on a path |
| 0x3301 | kGuideItemBoss |
| 0x0262 | kInlineBoss - Inline frames |
| 0xB318 | kTOPFrameItemBoss |
| 0xB603 | kTableItemBoss |
| 0xB608 | kTableModelBoss |
| 0x8C42 | kImportLinkBoss - Images |
| 0x8C44 | kBidirectionalLinkBoss - Linked texts (InCopy) |
| 0x10001 | kBookBoss |
| 0x1354C | kBookmarkBoss |
| 0x13501 | kHyperlinkBoss |
| 0x145D8 | kMultiStateObjectItemBoss - oObject status |
| 0x1450C | kPushButtonItemBoss - Buttons |
| 0x14509 | kFormFieldContentItemBoss |
| 0x1450A | kFormFieldItemBoss |
| 0x1450B | kAppearanceFormItemBoss |
| 0x1450D | kCheckBoxItemBoss |
| 0x1450E | kRadioButtonItemBoss |
| 0x1450F | kTextFieldItemBoss |
| 0x14510 | kListBoxFieldItemBoss |
| 0x14511 | kComboBoxItemBoss |
| 0x14512 | kSignatureFieldItemBoss |
-
Name Type Default Description Return int Class ID of existing object or 0 ref ItemRef - reference Check a range of document UIDs.
int main () { int i; ItemRef ref = item::alloc ();
for (i = 200; i < 301; i++) { item::define (ref, gFrame, i); wlog ("", "# UID %d : %d, 0x%X'\n", i, item::exists (ref), item::get_class (ref)); }
return 0; }- Since
- v3.3 R2489, 06.06.2011
- Available
- priint:comet InDesign® Plug-Ins, comet_pdf