The [$pdfToken] command.

Introduction

This page documents the syntax of the Tcl command associated with PDF views created with the [view create PDFView] command. The actual name of the command is the view's token (designated by $pdfToken in the rest of this document).

Synopsis

The formal syntax of the $pdfToken command is:

$pdfToken subcommand ?options?

The possible subcommands are described below. Depending on the subcommand, some options may be specified.

The [attributes] subcommand

This subcommand returns the PDF document's metadata. The complete syntax is:

$pdfToken attributes

It returns a dictionary containing some of the following keys:

Key	Description
Title	the title of the document
Author	the name of the author of the document
Subject	a description of the subject of the document
Creator	the name of the application that created the document content
Producer	the name of the application that produced the PDF data for the document
CreationDate	the document’s creation date
ModificationDate	the document’s last-modified date
Keywords	a list of keywords for the document
MajorVersion	the major version of the document
MinorVersion	the minor version of the document

The [blink] subcommand

This subcommand performs a flashing animation at a given position. The complete syntax is:

$pdfToken blink page x y

The arguments x and y are the coordinates of a point (in page coordinate system) on the page specified by the page argument. If a word is found at this position, a blinking animation is performed to draw the user's attention.
If you want to achieve a similar effect on a region delimited by character positions, see the [$pdfToken select] command.

The [clear] subcommand

This subcommand clears the current selection. The complete syntax is:

$pdfToken clear

To set a selection, see the [$pdfToken select] command.

The [count] subcommand

This subcommand the number of pages of the PDF document. The complete syntax is:

$pdfToken count

The [current] subcommand

This subcommand returns the current location in the pdf document. The complete syntax is:

$pdfToken current ?-destination?

The returned value depends on the -destination option :

without this option, the command returns only the zero-based index of the current page.
if the option is specified, the command returns a three element list containing the zero-based index of the current page and the x and y coordinates of the current point on this page, specified in page-space coordinates (see the [goto] subcommand).

When there are two pages in the view in a two-up mode (see the PDFView's -mode option), the current page is the left one. For continuous modes, the current page is the page crossing a horizontal line halfway between the view’s top and bottom bounds.

The [exec] subcommand

This subcommand lets you execute simple actions. The complete syntax is:

$pdfToken exec action

The action argument is the name of a standard command to perform on the currently selected region. It is the name of a Cocoa method that is defined in the PDFView class (or inherited from a parent class) and takes a unique nullable argument. The main methods available are given in the following table:

Movement	moveToBeginningOfDocument, moveToEndOfDocument
Navigation	goBack, goForward, goToFirstPage, goToLastPage, goToNextPage, goToPreviousPage
Scaling	zoomIn, zoomOut
Scrolling	scrollLineDown, scrollLineUp, scrollPageDown, scrollPageUp, scrollSelectionToVisible, scrollToBeginningOfDocument, scrollToEndOfDocument
Selection	selectAll
Miscellaneous	copy, print

The [flip] subcommand

This subcommand lets you flip a vertical coordinate on a given page. The complete syntax is:

$pdfToken flip page ycoord

By default, the origin of the page space coordinate system is at the lower-left corner of the current page. Some tools, such as SyncTeX, put the origin in the upper-left corner with the y-axis oriented downwards. This subcommand lets you convert the vertical coordinate from one system to the other for a given page.

The [goto] subcommand

This subcommand lets you navigate to a given position on a given page. The complete syntax is:

$pdfToken goto {page ?pos?}
$pdfToken goto -destination {page x y}

The command can take two forms. In the first form, the target is specified as a one or two element list containing the page index and the character index on the given page. If pos is not specified, it is set to 0.
In the second form, the -destination option indicates that the target is a point on the given page. The coordinates x and y of the point are specified in page-space coordinates. Page space is a 72 dpi coordinate system with the origin at the lower-left corner of the current page. This form can be useful, for example, when the dictionary returned by the [$pdfToken outline -action] command contains a point.
Note that page and character indexes are zero-based. The command raises an error if any of these indexes is out of range. See the [count] and [page numChars] commands to determine the number of pages and the number of characters respectively.

The [labels] subcommand

This subcommand gets the labels of all the document pages. The complete syntax is:

$pdfToken labels

The command returns a list of labels in ascending page order. This is useful for mapping page labels to page indexes.

The [outline] subcommand

This subcommand returns information about the outline associated with a PDF document. The complete syntax is:

$pdfToken outline 
$pdfToken outline -action indexPath

An outline is an optional component of a PDF document, useful for viewing the structure of the document and for navigating within it. Not all PDF documents have an outline tree, outlines are created by the document's author. They are usually displayed by PDF viewers in an outline view.
In the first form, this command returns the entire outline as a tree list. See the Tree List Format section for a description of the tree list format. The returned list is suitable for use with the -items option of the OutlineView.
In the second form, the -action option indicates that we want information about the action attached to a particular outline item. There are currently five kinds of actions:

GoTo	action of going to a specific location within the PDF document
Named	action with a defined method name to be executed
RemoteGoTo	go-to action that targets another document
ResetForm	action for getting and clearing fields in a PDF form
URL	action for getting a target URL

The outline item is specified using an index path within the outline tree (see the -indexPath option of the Browser view for an example of index path). The command returns a dictionary containing some of the following keys depending on the kind of action (kind and label are always provided):

kind	the kind of action
label	the outline's label
named	in integer representing a named action (see possible values here)
page	a page index in the PDF document
point	a point in PDF page space coordinates
pos	a char index on the page (or -1 if no char was found)
url	an URL

The [page] subcommand

This subcommand lets you get information about a particular page. The complete syntax is:

$pdfToken page pageIdx (annotations|bounds|label|numChars|rotation|string) ?value?

Pages are specified by their index: the index is zero-based, so page 1 has index 0, page 2 has index 1 etc. If the pageIdx argument is out of range, the command raises an error (see the [$pdfToken count] command to get the number of pages).
The third argument is the kind of information you want to obtain. The possible values are:

annotations: the annotations option tells whether to display annotations on the page. Its value is boolean. The default is 1.
bounds: the bounds option lets you get the bounds of a display box for the given page. There are several kinds of display boxes designated by an integer value which you can specify as the value argument. The possible values are given in the table below. If no value is specified, this is the same as 0 (Media Box).
Note that only the media box is required for a PDF document. If you request the bounds for the crop box, but the PDF does not include a crop box, the bounds for the media box are returned instead. If you request the bounds for other box types, and the PDF does not includes these types, the bounds for the crop box are returned instead.
label: the label option lets you get the label for the page. Typically, the label is "1" for the first page, "2" for the second page, and so on, but nonnumerical labels are also possible (such as "xxi").
numChars: the numChars option lets you get the number of characters on the page, including whitespace characters.
rotation: the rotation option lets you get or set the page rotation angle in degrees. The angle is a positive multiple of 90, like 0, 90, 180, or 270. A negative rotation is automatically converted to a corresponding positive rotation (for example, a -90 value is converted to 270).
string: the string option lets you get a string representing the text on the page.

Possible values for the bounds option:

Name	Value	Description
Media Box	0	physical medium for display or printing
Crop Box	1	visible region
Bleed Box	2	clip region for the page contents
Trim Box	3	intended boundaries of the finished page
Art Box	4	the page’s meaningful content including surrounding white space intended for display

The [search] subcommand

This subcommand lets you perform a literal search in the PDF document. The complete syntax is:

$pdfToken search ?-f (0|1)? ?-i (0|1)? ?-all? ?--? str {page pos}

The str argument is the string to search for. The {page pos} argument specifies the starting position. The command raises an error if page or pos are out fo range. Page and position indexes are zero-based.
The available options are:

-f (0\|1)	search backward or forward (default 1)
-i (0\|1)	ignore case (default 0)
-n	failed search returns empty string rather than raising an error
-all	return all matches
--	end of the options

Each match is represented as a pair of pairs of the form {page pos1} {page pos2}, suitable for use with the [$pdfToken select] and [$pdfToken text] commands. If the option -all is specified, the command returns a list of such pairs. If there is no match, the command raises an error if the -n option is not specified, or otherwise returns an empty string.

The [select] subcommand

This subcommand sets a selection on the PDF document. The complete syntax is:

$pdfToken select
$pdfToken select ?-blink? {page1 ?pos1?} ?{page2 ?pos2?}?

In the first form, the command returns the current selection. The start and end of the selection are specified as pairs containing the page index and the character index on the page.
In the second form, the command lets you set a selection. If pos1 is not specified, it is set to 0. If pos2 is not specified, it is set to the last character position on page2. If the second pair is not specified, then page2 is assumed to be equal to page1.
If the -blink option is specified, the selection is animated by first drawing a flashing rectangle around it.
Note that page and character indexes are zero-based. The command raises an error if any of these indexes is out of range. See the [count] and [page numChars] commands to determine the number of pages and the number of characters respectively.

The [text] subcommand

This subcommand gets the text contained in a given selection. The complete syntax is:

$pdfToken text {page1 ?pos1?} ?{page2 ?pos2?}?

The arguments have the exact same meaning as with the [$pdfToken select]. The returned string may contain linefeed characters.

Examples

Here are a few examples to demonstrate the $pdfToken command. Open the Tcl Shell (with ⌘Y) and enter the following commands, one by one. The «» symbols represent the shell's prompt.
Let us first create a document containing a PDF View:

«» set root [view root Document -frame {120 150 600 600}]
«» set pdfTkn [view create PDFView -frame {10 10 580 580} -parent $root]
«» set pdfFile [file join $HOME Help latex_guide.pdf]
«» view configure $pdfTkn -url "file://$pdfFile" -flexibility 18 
«» view show $root

There is now a command called $pdfTkn. Get the number of pages:

«» $pdfTkn count
67

Get the PDF file's atrributes:

«» $pdfTkn attributes
Creator {LaTeX with hyperref package} Producer pdfTeX-1.40.17 
Keywords {} CreationDate 1575890278 ModificationDate 1575890278 
MajorVersion 1 MinorVersion 5

Get the label of the first page (page at index 0):

«» $pdfTkn page 0 label
i

Get the number of characters on the first page:

«» $pdfTkn page 0 numChars
919

Let us rotate the first page 90 degrees clockwise:

«» $pdfTkn page 0 rotation 90

Rotate first page back to its initial orientation:

«» $pdfTkn page 0 rotation -90

Perform a few navigation actions:

«» $pdfTkn exec goToNextPage
«» $pdfTkn exec goToLastPage
«» $pdfTkn exec goToPreviousPage
«» $pdfTkn exec goToFirstPage
«» $pdfTkn exec selectAll
«» $pdfTkn exec zoomIn
«» $pdfTkn exec zoomOut

Select characters 100 to 200 on the first page:

«» $pdfTkn select {0 100} {0 200}

Last updated 2020-10-06 08:56:52