MuPdfWidget

ABU 7-nov-2021 - New download available v2.2

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

News

Just few days after the release of mupdf::widget 2.1, it comes mupdf::widget 2.2. Very little changes in the API, but now you can open two or more views even on the same PDF and then all the changes made in one view are instantly propagated to the other views. See the included demo "demo_sharedPDF.tcl" as a proof of concept.

See also Highlighter for a full app based on mupdf::widget

Download

  • [L1 ] Version 1.0 - Requires tclMuPdf version 1.x
  • [L2 ] Version 2.2 - Requires tclMuPDF version 2.x
    • Added methods "annot_flatten" and "annot_get"
    • BUGFIX: <<"clone" method raises an error if $win ha no attached pdf>>. Now FIXED
    • Ability to operate with multiple views even on the same PDF. See the included demo
    • DOCS and demos updated.
  • [L3 ] Version 2.1 - Requires tclMuPDF version 2.x
    • mupdf::widget is now a fully complaint 'scrollable widget' (added options -x/yscrollcommand and -x/yscrollincrement).
    • Internal improvement: the image is (eventually) repainted only once per event-loop.
    • subcommand nextpage/prevpage now returns true/false (false means that there's not a next/prev page)
    • DOCS updated.

Pre requirements

Here's a small screenshot of some included demo.

Image MuPdfWidgetSharedPdf

Here's another screenshot of a more complete app built with MuPdf ( see Highlighter ) Image MuPdfWidget-thumb2

  Reference manual - MuPdfWidget 1.0

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

  Reference manual - MuPdfWidget 2.2 (Nov-2021)

mupdf::widget 2.2 MuPDFWidget A basic PDF-viewer widget

a basic PDF-viewer widget

SYNOPSIS

package require Tk 8.6

package require mupdf::widget ?2.2?

  • mupdf::widget pathName ?pdfObj? ?option value...?
  • pathName attach
  • pathName attach ""
  • pathName attach pdfObj ?pageNum?
  • pathName cget option
  • pathName configure ?option? ?value option value ...?
  • pathName reqsize
  • pathName clone newPath
  • pathName zoom
  • pathName zoom zf
  • pathName zoomfit mode
  • pathName rzoom delta
  • 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 n? ?-currpageonly true/false?
  • pathName search ""
  • pathName search
  • pathName selectionclear
  • pathName annot_get
  • pathName annot_add type color
  • pathName annot_setcolor color
  • pathName annot_delete
  • pathName annot_flatten
  • pathName win2page x y
  • pathName win2PDFcoords x y

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 pdfObj, you can use it for working with an instance of a mupdf::widget.

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

The general form for creating a widget is:

mupdf::widget pathName ?pdfObj? ?option value...?
This command command creates the pathName widget and returns a new Tcl command whose name is pathName. If pdfObj is not specified, then the widget starts 'empty', with no attached PDF. You should then attach a pdfObj later (see below).

Note that a mupdf::widget starts with a basic set of interaction-controls (bindings) for scrolling the pages, selecting text and annotations; it's your responsability to choose whick kind of UI you want to implement (menus, buttons) and how to respond to some custom events (text/annotation selection) by binding these controls and events with the basic actions mupdf::widget provides.

WIDGET OPTIONS

-background
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.
-extramargin
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.
-selectioncolor
The color used for highlighting the selected text. Default is yellow.
-shadow
a list of gray shades for rendering a pseudo shadow under the page. Note: since currently shadows are only gray-level shadows option -background should be a gray shade,too.
-zoomratio
A coefficient used for relative zoom. See subcommand rzoom.
-xscrollcommand
-yscrollcommand
-xscrollincrement
-yscrollincrement
Same as the standard options to communicate with scrollbars

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 the widget pathName:
pathName attach
return the currently attached pdfObj or {}.
pathName attach ""
break the link with the attached pdfObj (if any). An 'empty' page is displayed.
pathName attach pdfObj ?pageNum?
attach the pdfObj object (created by mupdf::open) and display the page pageNum or the closest one to pageNum. If pageNum is not specified, then page 0 (the first page) is displayed.
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 reqsize
return a list of two integer representing the width and height (in pixel) of the zoomed page including the -extramargin. Note that this size is just the 'virtual' size of the zoomed page since just the visible area of the page (plus some extra 'margin') is rendered as a bitmap by the the underling mupdf engine.
pathName clone newPath
creates a new mupdf::widget named newPath as a clone of pathName.
pathName zoom
get the current zoom-factor
pathName zoom zf
set the current zoom-factor
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 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 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. This subcommand returns false if there's not a next page, else it returns true.
pathName prevpage
show the previous page. This subcommand returns false if there's not a previous page, else it returns true.
pathName search text ?-startpage n? ?-currpageonly true/false?
start searching text and highlight all its occurrencies starting from the current page, or from page n if specified. If option -currpageonly is true, the the search is limited to the current page (or from the page specificed as -startpage).
pathName search ""
reset the text-to-search.
pathName search
get the currently set text-to-search.
pathName selectionclear
turn off the highlights on the currently selected text.
pathName annot_get
This method should be used only after an existing annotation has been selected, i.e. in response to the <<MuPDF.AnnotSelected>> event.
pathName annot_add type color
This method should be used only after receiving the event <<MuPDF.TextSelected>>. The selected text is transformed in a pdf-annotation. type must be highlight, underline, strikeout or squiggly. color must be a symbolic color (eg, red, ligthblue, ,,,) or #rrggbb
pathName annot_setcolor color
This method should be used only after an existing annotation has been selected, i.e. in response to the <<MuPDF.AnnotSelected>> event. color must be a symbolic color (eg, red, lightblue, ,,,) or #rrggbb
pathName annot_delete
This method should be used only after an existing annotation has been selected, i.e. in response to the <<MuPDF.AnnotSelected>> event.
pathName annot_flatten
This method should be used only after an existing annotation has been selected, i.e. in response to the <<MuPDF.AnnotSelected>> event.
pathName win2page x y
given a screen point (relative to the origin of the pathName widget), return the corresponding point of the PDF page (in 'points' unit), accordling to the MuPDF coord-sys where (0,0) is the top-left corner of the page.
pathName win2PDFcoords x y
given a screen point (relative to the origin of the pathName widget), return the corresponding point of the PDF page (in 'points' unit), accordling to the standard PDF coord-sys where (0,0) is the bottom-left corner of the page.

BINDINGS

mupdf::widget provides only basic built-in bindings for scrolling the page. The behavior of mupdf::widget can be enhanced by defining new bindings for individual widgets or by redefining the class bindings.

  • The arrows-keys can be used for scrolling a large page as do the mousewheel or two-finger gesture on a touchpad.
  • On Windows you can also use an horizontal two-finger gesture for horizontal scrolling; on other platforms you should use <shift>+<mousewheel>.

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 "Z"

bind MuPDFWidget <Key-z> { %W zoomfit xy }

Change the page using the PageUp, PageDown keys

bind MuPDFWidget <Key-Next> { %W nextpage }
bind MuPDFWidget <Key-Prior> { %W prevpage }

VIRTUAL EVENTS

MUPDFWidget defines a few virtual events for the purposes of notification.

  • Any time the widget is resized, the virtual event <<MuPDF.Configured>> will be generated.
  • Any time the current page is changed, the virtual event <<MuPDF.PageLoaded>> will be generated. Binding scripts can use the %d value for getting the new page-number.
  • Any time an annotation is selected, the virtual event <<MuPDF.AnnotSelected>> will be generated. Binding scripts can use the %x and %y value for getting the coords of the selection, and the %d value for getting the annotation-type.
  • Any time a text is selected, the virtual event <<MuPDF.TextSelected>> will be generated.

SHARED VIEWS and SHARED CHANGES

Starting with mupdf::widget 2.0, programmers were able to create multiple instances of mupdf::widget even working on the same PDF (e.g. two views on the same PDF). This worked but with one severe limitation: changes made through one view (e.g. add/change/delete annotations) weren't propagated to other views; as a matter of fact others views were kept in sync only after a full-page reload. Starting with mupdf::widget 2.2, all the widget instances working on the same PDF are kept in sync, so that changes made in one view (add/change/remove annotations..) are instantly propagated to all the widget instances working on the same doc.

BUGS, IDEAS, FEEDBACK

  • -

KEYWORDS

PDF, Snit, widget

CATEGORY

widgets

COPYRIGHT

 Copyright (c) 2021, by A.Buratti