***mupdf::widget*** is a fully customizable widget for displaying PDF-files, based on the package tclMuPdf, a tcl-binding of the popular MuPDF framework.
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::widgetpathNamepdfHandle ?optionvalue...?
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 responsability to choose whick 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:
pathNamesubCommand ?arg ...?
The following subCommands are available for pathName:
pathNamecgetoption
return the current value of the configuration option given by option. Option may have any of the values accepted by the mupdf::widget command.
pathNameconfigure ?option? ?valueoptionvalue ...?
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.
pathNamepdfHandle
get the current pdfHandle
pathNamepdfHandlepdfHandle
associate the viewer with a different pdfHandle. Restart from page 0.
pathNamewin2pagexy
Conversion between coord-systems: from screen-point (x,y) of the widget, to the corresponding point in the pdf-page coordinate system.
pathNamezoom
get the current zoom-factor
pathNamezoomzf
set the current zoom-factor
pathNamerzoomdelta
multiply-or-divide the zoom-factor by the -zoomratio coefficient. If delta is positive, zoom-factor is multiplied, else it's divided
pathNamezoomfitmode
set the optimal zoom-factor for displaying the page. mode can be x (best-width) y (best-height) xy (best fit).
pathNamecentermode
align the center of the page with the center of the window. mode can be x, y or xy.
pathNamealignside
align the page on a side of the window. side can be top, bottom, left or right.
pathNamescrolldWxdWy
scroll the viewport by dWx,dWy pixels.
pathNamescanmarkxy
pathNamescandragtoxy ?gain?
The scan subcommands is used to implement scanning. See the scan subcommand of the canvas widget.
pathNamexview ?args?
pathNameyview ?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.
pathNamepage
get the current page number (first page is 0).
pathNamepagepagenumber
show the page pagenumber (first page is 0). This subcommand returns an error if pagenumber is out of bounds.
pathNamenextpage
show the next page. If current page is the last page, no error is raised.
pathNameprevpage
show the previous page. If current page is the first page (page 0), no error is raised.
pathNamesearchtext ?-startpagepagenumber?
start searching text from the current page, or from pagenumber if specified. All the occurrencies of text will be highlighted
pathNamesearch""
reset the text-to-search.
pathNamesearch
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 predefenid, 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)