[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 anyway

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;
}

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 (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 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 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"

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

Since

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

frame::fit
frame::fit_better
frame::fit_image
comet.CFrame.fit

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