tkdvi::browser - Create and manipulate DVI browser megawidgets

package require tkdvi

tkdvi::browser::browser pathName ?options?

Specifies whether a red `cross-hair' will be displayed at the current mouse cursor position when button 3 is depressed with the Control key held down. This makes it possible to check conveniently whether features on the DVI page align. The default is 1 (alignment ruler enabled). This specifies the widget's action when button 1 is pressed on a DVI display. It can be either magnify or draw. If magnify, a magnification window is popped up at the current cursor position (see MAGNIFICATION WINDOW below). If draw, free-hand annotation of the display is enabled (see FREE-HAND ANNOTATION below). The default is magnify. Specifies the file to be displayed in the widget. This must have been previously opened using the dvi::code command. Specifies the color to be used for free-hand annotations (see FREE-HAND ANNOTATION below). Any standard Tk color specification is acceptable. The default is red. If set to 1, extends the widget to cover all of the screen (if the window manager allows this). If set to 0, the height and width of the widget are constrained to 0.9 times the screen height and width, respectively. The default is 0. Specifies whether a `rubber line' measuring device will be displayed at the current mouse cursor position when button 3 is depressed with the Shift key held down. On a subsequent button 3 drag operation, the distance between the start of the drag operation and the current mouse cursor positions, in units of the DVI document, will be displayed in the tool bar's page number area. The default is 1 (measuring `tape' enabled). Specifies whether a menu bar should be displayed across the top of a top-level DVI megawidget (1) or whether the menu bar should be suppressed (0). The default is 1. Specifies the display mode for the file. The available modes are listed in the variable tkdvi::browser::DisplayModeKeys and include the following: single displays a single full-size page; spread displays a `spread' of two adjacent pages (like a book); overview shows 16 pages in the area otherwise taken up by a single page-the text in such a display is quite unreadable but it is easy to see where page breaks, chapter heads and floating items go. The default is single. If set to 1, a tkdvi::pagesel megawidget containing the TeX file's page numbers is displayed to the left of the DVI display. This enables direct access to pages in the DVI file; see tkdvi::pagesel(3) for details. If set to 0, no such widget is displayed. The default is 1. Specifies whether to include scroll bars for the widget contents. The value can be an empty string (for no scroll bars), x, y or xy (for scroll bars in the corresponding direction). Scrolling is possible by dragging mouse button 2 even if scroll bars are disabled. The default is xy. Specifies the linear shrink factor to be applied to the material displayed in the widget. This can be any positive integer. The default is 8, which gives reasonable results when using 600dpi fonts. Specifies the `paper' size of the material displayed in the widget. Possible values include a4 (and other DIN sizes from a0 to a7), letter, and legal. All these sizes can have a r appended to indicate landscape (rotated) format. The default is a4. This experimental feature will eventually allow users to jump to the general area in a TeX source file that corresponds to a place in the DVI output by clicking on the position in question with the Meta key held down. This needs support in a suitable text editor, and is disabled by default. Specifies the title to be used in the window title if the widget is used as a top-level window. The sequence %f in the title will be replaced by the current `base' file name (without the directory or .dvi extension). The default is `tkdvi: %f'. If set to 1, a `tool bar' containing various icons and displays is displayed across the top of the widget, immediately below the menu bar if it exists. If set to 0, no tool bar is displayed. The default is 1. If set to 1, the widget is generated as a Tk toplevel widget (it is managed directly by the window manager). If set to 0, the widget is generated as a Tk frame widget for inclusion in a standard Tk GUI. A menu bar is only available on toplevel widgets. This option can only be specified when the megawidget is created; it cannot be changed afterwards. The default is 1.

The tkdvi::browser::browser command creates a new window (given by the pathName argument) and makes it into a megawidget suitable for the display of DVI material. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the megawidget. The tkdvi::browser::browser command returns its pathName argument. At the time this command is invoked, there must not exist a window named pathName, but pathName's parent must exist.

A DVI browser is a megawidget that displays pages from a DVI file. The display can be manipulated and changed in various ways, using the commands described below.

The tkdvi::browser::browser command creates a new Tcl command whose name is pathName. This command may be used to invoke various operations on the widget. It has the following general form: pathName option ?arg arg ...? Option and the args determine the exact behavior of the command. The following commands are possible for DVI browser widgets:

pathName cget option

Returns the current value of the configuration option given by option. Option may have any of the values accepted by the tkdvi::browser::browser command.

pathName close

Destroys the widget and closes the DVI document being displayed.

pathName configure ?option? ?value option value ...?

Query or modify the configuration options of the widget. If no option is specified, returns a list describing all of the available options for pathName (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. Option may have any of the values accepted by the tkdvi::browser::browser command, with the exception that the value of the -toplevel configuration option cannot be changed.

pathName gotopage page

Causes the DVI page page to be displayed instead of the current page. page may be either a TeX page specification, where TeX page specifications are defined as sequences of up to 10 integers or *'s, separated by dots, or a `physical' page number in the form of an integer preceded by =.

pathName nextpage ?offset?

Causes the DVI page offset pages away from the currently displayed DVI page to be displayed instead of the current page. offset may be any integer (positive or negative) but the resulting page number is reduced modulo the number of pages in the file to give a page number that is actually valid. I.e., moving to the next page when the last page is being shown causes the first page to be displayed. offset defaults to 1.

pathName open ?file?

Causes the currently-displayed DVI document to be replaced by file if file can be opened. If file is not specified, a Tk file selector box is displayed.

pathName print ?-marked?

(Not finished.) Invokes a suitable command to cause the DVI document to be printed via a suitable DVI-to-printer conversion program. If the -marked option is given, only those pages that have been marked in the widget's page selector are printed if the DVI-to-printer conversion program allows this. Currently this invokes dvips; the implementation is by no means finished.

pathName reload

Causes the currently-displayed DVI document to be re-loaded from the corresponding DVI file.

The material on a DVI page is usually displayed at reduced size. The magnification window makes it possible to look at part of the DVI page at the full resolution of the underlying fonts (often 600 dpi). It is accessible when the -b1action configuration option is set to magnify. The window can be popped up using mouse button 1, and moved about the page by dragging with mouse button 1. Releasing the button makes it go away. Pressing mouse button 1 with no modifier keys results in a fairly small but fast magnification window; holding the Shift or Control keys when pressing mouse button 1 gives a larger but somewhat slower magnification window.

As an aid to presentations, when the -b1action configuration option is set to draw, material on a DVI page may be underlined, circled, etc. by pressing and dragging mouse button 1. The annotations are hidden and exposed as appropriate when paging back and forth, but changing the display mode or the shrink factor removes them. The color of the annotations can be specified via the -freehandcolor configuration variable.

Tk automatically creates bindings for DVI browser widgets that give them the following default behavior.

[1]

Pressing mouse button 1 either invokes the magnification window (see MAGNIFICATION WINDOW) or starts a free-hand annotation (see FREE-HAND ANNOTATION), depending on the value of the -b1action configuration option. Accordingly, dragging with mouse button 1 either moves the magnification window or continues the annotation; releasing mouse button 1 removes the magnification window or finishes the annotation as appropriate. For the magnification window, pressing the mouse button with the Shift or Control keys down results in a larger size of magnification window.

[2]

The view in the widget can be adjusted by dragging with mouse button 2.

[3]

Pressing mouse button 3 with no modifier keys depressed displays the widget's menu as a pop-up menu. This menu is identical to the one otherwise displayed in the widget's menu bar if the widget is a top-level widget and the menu bar has not been disabled.

[4]

Pressing mouse button 3 with the Shift key down invokes the measuring device, if this has not been disabled using the -measuretape configuration option. Dragging with mouse button 3 serves to measure distances on the DVI page. Releasing mouse button 3 ends the measuring process.

[5]

Pressing mouse button 3 with the Control key down invokes the alignment rulers if this has not been disabled using the -alignmentruler configuration option. Dragging with mouse button 3 moves the aligment rulers, and releasing mouse button 3 removes them.

[6]

The Left, Right, Up and Down keys move the view on the DVI page in the respective direction.

[7]

The `minus', `p' and `b' keys cause the previous page to be displayed in the window, where the various display modes (spread or overview) are taken into account such that movement is in increments of 2 or 16 pages, respectively. Similarly, the `plus', `n' and `space' keys cause the next page to be displayed.

[8]

The `underscore' key is like `minus' but moves by 10 pages instead of 1, while the `asterisk' key is similarly like 'plus'.

[9]

The `1', `2', ..., `0' keys can be used to build up a `numerical argument' for use by later keyboard commands such as `g'.

[10]

The `g' key jumps to the (physical) page given by the current numerical argument.

[11]

Pressing one of `1', `2', ..., `0' with the Control key down will set the shrink factor (see configuration option -shrink) to the corresponding value (10 in the case of 0).

[12]

The `o', `s', and `d' keys set the current display mode (see configuration option -mode) to overview, shrink, or spread (`double'), respectively.

[13]

The `c' key closes the current DVI document.

[14]

The `r' key reloads the current DVI document from the corresponding DVI file (see the pathName reload command).

[15]

The `f' key toggles the value of the -fullscreen configuration option.

[16]

The `C' (capital C) key removes any free-hand annotations for the document. The `Delete' key removes the free-hand annotation that is currently under the mouse cursor.

The widget is fairly fast (considering that no dedicated optimization has been done yet). Note that, due to the way free-hand annotations are being built up, there may be a noticeable `lag' when very long lines are being drawn.

The following issues will hopefully be resolved in later versions of the software:

[1]

Rendering of overlapping characters doesn't work right.

[2]

There is no way to display Encapsulated PostScript (EPS) files, which is something that LaTeX users like to do.

browser, DVI, widget