# mupdf::widget(n) 2.0 MuPdfWidget "A basic PDF-viewer widget"

## Name

mupdf::widget - a basic PDF-viewer widget

## Synopsis

- package require Tk 8.6
- package require mupdf::widget ?2.0?

- 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_add type color
- pathName annot_setcolor color
- pathName annot_delete
- 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.

## 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. 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 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_add type color

  This method could 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 could 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 could 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 id 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.

## BUGS, IDEAS, FEEDBACK

- -

## Keywords

PDF, Snit, widget

## Category

widgets

## Copyright

Copyright © 2021, by A.Buratti