MuPdfWidget

ABU 06-mar-2017

mupdf::widget is a fully customizable widget for displaying PDF-files, based on the package tclMuPdf, a tcl-binding of the popular MuPDF framework.

Download

  • [1 ] Pure-tcl package including a small demo

Pre requirements

Here's a small screenshot of the demo. Note that this demo implements only a minimum set of interaction-controls (UI); it's your responsibility to choose which kind of UI you want to implement (menus, buttons, mouse gestures, ..) and then link these controls with the basic 'actions' mupdf::widget provides.

Image MuPdfWidget-thumb

  Reference manual

mupdf::widget 1.0 A basic PDF-viewer widget

a basic PDF-viewer widget

SYNOPSIS

package require Tk 8.5

package require mupdf::widget ?1.0?

  • mupdf::widget pathName pdfHandle ?option value...?
  • pathName cget option
  • pathName configure ?option? ?value option value ...?
  • pathName pdfHandle
  • pathName pdfHandle pdfHandle
  • pathName win2page x y
  • pathName zoom
  • pathName zoom zf
  • pathName rzoom delta
  • pathName zoomfit mode
  • pathName center mode
  • pathName align side
  • pathName scroll dWx dWy
  • pathName scan mark x y
  • pathName scan dragto x y ?gain?
  • pathName xview ?args?
  • pathName yview ?args?
  • pathName page
  • pathName page pagenumber
  • pathName nextpage
  • pathName prevpage
  • pathName search text ?-startpage pagenumber?
  • pathName search ""
  • pathName search

DESCRIPTION

mupdf::widget is a fully customizable widget for displaying PDF-files, based on the package tclMuPdf, a tcl-binding of the popular MuPDF framework. You need to install tclMupdf, then use it for opening PDF files. Once a PDF-file has been opened, i.e. you got a pdfHandle, you can use it for creating and working with an instance of a mupdf::widget.

 # choose a PDF file ...
set PDFname  "/docs/abc.pdf"
 # create a PDFhandle
set PDFhandle [mupdf::open $PDFname]
 # create a widget for PDFhandle 
mupdf::widget .pdfWin $PDFhandle
 # display the widget .pdfW
pack .pdfWin -expand 1 -fill both

The general form for creating a widget is:

mupdf::widget pathName pdfHandle ?option value...?
This command command creates the pathName widget and returns a new Tcl command whose name is pathName.

Note that a mupdf::widget starts with a minimum set of interaction-controls (UI); it's your responsibility to choose which kind of UI you want to implement (menus, buttons, mouse gestures, ..) and then link these controls with the basic 'actions' mupdf::widget provides.

WIDGET OPTIONS

-bg
The background color of the underlying canvas.
-cursor
The mouse cursor to be used for the widget. The value may have any of the forms acceptable to Tk_GetCursor. In addition, if an empty string is specified, it indicates that the widget should defer to its parent for cursor specification.
-pagemargin
A non-negative value indicating the extra space surrounding the displayed PDF pages.
-foundtextcolor
The color used for highlighting the searched words. Default is red. See subcommand search.
-zoomratio
A coefficient used for relative zoom. See subcommand rzoom.

WIDGET COMMANDS

The mupdf::widget command creates a widget and a new Tcl command whose name is pathName. pathName may be used to invoke various operations on the widget. It has the following general form:

pathName subCommand ?arg ...?
The following subCommands are available for pathName:
pathName cget option
return the current value of the configuration option given by option. Option may have any of the values accepted by the mupdf::widget command.
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, thena 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 mupdf::widget command.
pathName pdfHandle
get the current pdfHandle
pathName pdfHandle pdfHandle
associate the viewer with a different pdfHandle. Restart from page 0.
pathName win2page x y
Conversion between coord-systems: from screen-point (x,y) of the widget, to the corresponding point in the pdf-page coordinate system.
pathName zoom
get the current zoom-factor
pathName zoom zf
set the current zoom-factor
pathName rzoom delta
multiply-or-divide the zoom-factor by the -zoomratio coefficient. If delta is positive, zoom-factor is multiplied, else it's divided
pathName zoomfit mode
set the optimal zoom-factor for displaying the page. mode can be x (best-width) y (best-height) xy (best fit).
pathName center mode
align the center of the page with the center of the window. mode can be x, y or xy.
pathName align side
align the page on a side of the window. side can be top, bottom, left or right.
pathName scroll dWx dWy
scroll the viewport by dWx,dWy pixels.
pathName scan mark x y
pathName scan dragto x y ?gain?
The scan subcommands is used to implement scanning. See the scan subcommand of the canvas widget.
pathName xview ?args?
pathName yview ?args?
These subcommands are used to query and change the horizontal/vertical position of the page displayed in the window. They are usually used for interacting with scrollbars. See the xview,yview subcommands of the canvas widget.
pathName page
get the current page number (first page is 0).
pathName page pagenumber
show the page pagenumber (first page is 0). This subcommand returns an error if pagenumber is out of bounds.
pathName nextpage
show the next page. If current page is the last page, no error is raised.
pathName prevpage
show the previous page. If current page is the first page (page 0), no error is raised.
pathName search text ?-startpage pagenumber?
start searching text from the current page, or from pagenumber if specified. All the occurrences of text will be highlighted
pathName search ""
reset the text-to-search.
pathName search
get the currently set text-to-search.

BINDINGS

mupdf::widget provides only basic built-in bindings for zooming and panning. The behavior of mupdf::widget can be changed by defining new bindings for individual widgets or by redefining the class bindings. The predefined, built-in binding are:

  • zooming Press the < + > or < - > keys. Note that the zoom coefficient may by adjusted with the -zoomratio configuration option.
  • panning Press Left-Button and drag

Redefining bindings

mupdf::widget subcommands may be associated with different kind of UI controls, such as buttons, menus, or they may be bound to events. It is recommended to redefine and add new bindings at widget-class level. The name of the widget-class for mupdf::widget is MuPdfWidget. Just few examples: Associate the zoomfit subcommand with the keyboard's key "C"

bind MuPdfWidget <Key-c> { %W zoomfit xy }

Scroll the page with <MouseWheel> (or two finger gesture on touchpads)

bind MuPdfWidget <MouseWheel> { %W scroll 0 [expr -%D] }

EVENTS

.. Not yet implemented ..

BUGS, IDEAS, FEEDBACK

  • -
  • -

KEYWORDS

PDF, Snit, widget

CATEGORY

widgets

COPYRIGHT

 Copyright (c) 2017, by A.Buratti