Link

Represents a pointer to somewhere (this document, other documents, the internet). Links exist per document page, and they are forward-chained to each other, starting from an initial link which is accessible by the Page.firstLink property.

There is a parent-child relationship between a link and its page. If the page object becomes unusable (closed document, any document structure change, etc.), then so does every of its existing link objects – an exception is raised saying that the object is “orphaned”, whenever a link property or method is accessed.

Attribute	Short Description
Link.setBorder()	modify border properties
Link.border	border characteristics
Link.colors	border line color
Link.dest	points to link destination details
Link.isExternal	external link destination?
Link.next	points to next link
Link.rect	clickable area in untransformed coordinates.
Link.uri	link destination
Link.xref	xref number of the entry

Class API

class Link

setBorder(border)

PDF only: Change border width and dashing properties.

Parameters

border (dict) – a dictionary as returned by the border property, with keys "width" (float), "style" (str) and "dashes" (sequence). Omitted keys will leave the resp. property unchanged. To e.g. remove dashing use: "dashes": []. If dashes is not an empty sequence, “style” will automatically set to “D” (dashed).

colors

Meaningful for PDF only: A dictionary of two lists of floats in range 0 <= float <= 1 specifying the stroke and the interior (fill) colors. If not a PDF, None is returned. The stroke color is used for borders and everything that is actively painted or written (“stroked”). The lengths of these lists implicitely determine the colorspaces used: 1 = GRAY, 3 = RGB, 4 = CMYK. So [1.0, 0.0, 0.0] stands for RGB color red. Both lists can be [] if no color is specified. The value of each float f is mapped to the integer value i in range 0 to 255 via the computation f = i / 255.

Return type

dict

border

Meaningful for PDF only: A dictionary containing border characteristics. It will be None for non-PDFs and an empty dictionary if no border information exists. The following keys can occur:

• width – a float indicating the border thickness in points. The value is -1.0 if no width is specified.

• dashes – a sequence of integers specifying a line dash pattern. [] means no dashes, [n] means equal on-off lengths of n points, longer lists will be interpreted as specifying alternating on-off length values. See the Adobe PDF Reference 1.7 page 217 for more details.

• style – 1-byte border style: S (Solid) = solid rectangle surrounding the annotation, D (Dashed) = dashed rectangle surrounding the link, the dash pattern is specified by the dashes entry, B (Beveled) = a simulated embossed rectangle that appears to be raised above the surface of the page, I (Inset) = a simulated engraved rectangle that appears to be recessed below the surface of the page, U (Underline) = a single line along the bottom of the annotation rectangle.

Return type

dict

rect

The area that can be clicked in untransformed coordinates.

Type

Rect

isExternal

A bool specifying whether the link target is outside of the current document.

Type

bool

uri

A string specifying the link target. The meaning of this property should be evaluated in conjunction with property isExternal. The value may be None, in which case isExternal == False. If uri starts with file://, mailto:, or an internet resource name, isExternal is True. In all other cases isExternal == False and uri points to an internal location. In case of PDF documents, this should either be #nnnn to indicate a 1-based (!) page number nnnn, or a named location. The format varies for other document types, e.g. uri = '../FixedDoc.fdoc#PG_2_LNK_1' for page number 2 (1-based) in an XPS document.

Type

str

xref

An integer specifying the PDF xref. Zero if not a PDF.

Type

int

next

The next link or None.

Type

Link

dest

The link destination details object.

Type

linkDest