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

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

a basic PDF-viewer widget

SYNOPSIS

package require Tk 8.6

package require MuPDF 2.0

package require mupdf::widget ?2.3?

• 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_settype type ?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. Note: on MacOS, only the outline is rendered; On Windows and Linux the box around the found words is filled with a stippled color.

-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_settype type ?color?

This method should be used only after an existing annotation has been selected, i.e. in response to the <<MuPDF.AnnotSelected>> event. type must be highlight, underline, strikeout or squiggly. 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) 2023, by A.Buratti