comet.hyperlink

Methods

comet.hyperlink.createPageDestination(document, target, name='', shared=False)

Create a destination for hyperlinks pointing to a document page

Parameters

• document (CDocument | None) –

  The document to create the destination in.

  The parameter type can be:

  • CDocument

    A defined document

  • None

    Use the active script document

• target (tuple[CDocument, int] | tuple[str, int] | CPage | int) –

  The target page.

  The parameter type can be:

  • tuple [CDocument, int]

    Document, page index

  • tuple [str, int]

    Full path to a document, page index

  • CPage

    A page.

    When the page is in a different document than the source frame, the document must have been saved at least once.

  • int

    Page index in the active script document (may be different from the source document). The script document must have been saved at least once.

• name (str) –

  The name of the destination.

  • Empty str: Use the default ‘Anchor’

Returns

The newly created destination

Return type

CHyperlinkDestination

Raises

• TypeError – When parameter types are invalid

• CometError – When parameter target is of type CPage from a different document which has never been saved

Available

CScript

• hyperlink::create_pagedest

• hyperlink::frame_create_pagedest

comet.hyperlink.createTextDestination(document, target, name='', shared=False)

Create a destination for hyperlinks pointing to a piece of text

Parameters

• document (CDocument | None) –

  The document to create the destination in.

  The parameter type can be:

  • CDocument

    A defined document

  • None

    Use the active script document

• target (tuple[CFrame, int] | tuple[CTextModel, int]) –

  The target text to link to.

  The parameter type can be:

  • tuple [CFrame, int]

    Frame, anchor index

  • tuple [CTextModel, int]

    Text model, anchor index

• name (str) –

  The name of the destination

  • Empty str: Use the default ‘Anchor’

• shared (bool) – Create a shared destination inside the document?

Returns

The newly created destination

Return type

CHyperlinkDestination

Raises

• TypeError –

  • When parameter types are invalid

  • When parameter document is None and there is no script document

• ValueError – When parameter target is empty

Available

CScript

• hyperlink::create_urldest

• hyperlink::frame_create_urldest

comet.hyperlink.createURLDestination(document, target, name='', shared=False)

Create a destination for hyperlinks pointing to a URL

Parameters

• document (CDocument | None) –

  The document to create the destination in

  The parameter type can be:

  • CDocument

    A defined document

  • None

    Use the active script document

• target (str) –

  The full target URL for the destination.

  E-Mail URLs like mailto:name@…subject=…. as possible aswell, where the subject part is optional.

• name (str) –

  The name of the destination

  • Empty str: Use the default ‘Anchor’

• shared (bool) – Create a shared destination inside the document?

Returns

The newly created destination

Return type

CHyperlinkDestination

Raises

• TypeError –

  • When parameter types are invalid

  • When parameter document is None and there is no script document

• ValueError – When parameter target is empty

Available

CScript

• hyperlink::create_urldest

• hyperlink::frame_create_urldest

comet.hyperlink.create(source, target, name='')

Create a hyperlink by providing a source and an already created destination

Parameters

• source (CFrame | tuple[CFrame, int, int]) –

  The source for this link.

  The parameter type can be:

  • CFrame

    Create a link from a frame.

  • tuple [CFrame, int, int]

    Create a link from a piece of text.

    Values are [text frame, start, length].

    length may be comet.kEnd == until the end.

    Text indices are justified.

• target (CHyperlinkDestination) – The defined target which must be defined in the same document as the source

• name (str) –

  The name of the hyperlink

  • Empty str: Use up to 32 characters of the source text if any, else use ‘Hyperlink’

Returns

The newly created link

Return type

CHyperlink

Raises

• TypeError –

  • When parameter types are invalid

  • When parameter source is of type tuple [CFrame, int, int] and the frame is not a text frame

• ValueError – When parameter target is not in the same document as source

Available

CScript

• hyperlink::create_urldest

• hyperlink::frame_create_urldest

• hyperlink::create_pagedest

• hyperlink::frame_create_pagedest

comet.hyperlink.find(scope)

Find all existing hyperlinks in a certain scope.

Parameters

scope –

The scope to search in.

The parameter type can be:

• CDocument

  Get all hyperlinks in a document

• CFrame

  Get the hyperlink on a frame

• tuple [CTextModel, int, int]

  Get all hyperlinks in a text model.

  Parameters are [textmodel, start, length]

  Links which are partially in the range are also found.

Returns

A list of found hyperlinks

Return type

list[CHyperlink]

Raises

TypeError – When parameter types are invalid

Available

comet.hyperlink.findCrossRefs(scope, name='', classID=0, recordID=None, findInBook=False, calcTextCoords=False)

Find all cross reference destinations of a given name and a given Comet ID.

Cross reference destinations are created using CTextModel.insertCrossRef(), with the <w2cross> tag or using the product pool panel submenu Insert Cross Reference.

A detailed description about Comet cross references can be found here

While creating cross reference destinations, InDesign® takes care of unique names by appending a counter to the names.

This is the reason why you may have more than one cross reference destination with the same name and ID in the document.

The find function ignores this counter and will find all cross reference destinations beginning with the given name and/or Comet ID string containing of classid, ID, ID2, ID3 and StringID of the given Comet-ID.

You may wish to search all documents of the book containing the given document.

In this case all documents of the book will be opened and closed in the background automatically.

The Comet document watch mechanism is turned off in this situation.

Cross reference destinations in overset will not be found!

Parameters

• scope (CDocument) – The document to search in

• name (str) –

  Name of the destination to search for.

  Find all destinations beginning with the given name.

  May be empty.

• classID (int) – Class ID of the following comet object

• recordID (tuple[int, int, int, str] | CIDType) –

  Comet object ID.

  The parameter type can be:

  • None

    Ignore

  • CIDType

  • tuple [int, int, int, str]

    ID1, ID2, ID3, StringID

• findInBook (bool) – Search in all documents of the book the document belongs to?

• calcTextCoords (bool) –

  Calculation of text coordinates is expensive and must therefore be enabled manually.

  • False : Not needed

  • True : Calculate coordinates (in points relative to the text frame). Y is the baseline position.

Returns

A list of found crossrefs

Return type

list[CCrossRef]

Raises

TypeError – When parameter types are invalid

Available

CScript

hyperlink::find

comet.hyperlink.getNextUniqueKey(document=None)

Get next available unique hyperlink key of a document.

The function is useful if you want to create hyperlinks using TaggedText.

See here for more information

Parameters

document (None | CDocument) –

The document to get the next key for

• None: Active script document

Returns

The next unique hyperlink key

Return type

int

Raises

TypeError –

• When parameter types are invalid

• When parameter document is None and there is no script document

Available

CScript

hyperlink::get_next_unique_key