[ABU] 4-nov-2021 - New download available v2.1 '''mupdf::widget''' is a fully customizable widget for displaying PDF-files, based on the package [tclMuPDF], a tcl-binding of the popular MuPDF framework. See also [Highlighter] for a full app based on '''mupdf::widget''' ***Download *** * [https://sourceforge.net/projects/irrational-numbers/files/MuPdfWidget-1.0.zip/download] Version 1.0 - Requires tclMuPdf version 1.x * [https://sourceforge.net/projects/irrational-numbers/files/MuPDFWidget-2.1.zip/download] 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 *** * [snit] * [tclMuPdf] 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] 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 { %W zoomfit xy } ====== Scroll the page with (or two finger gesture on touchpads) ====== bind MuPdfWidget { %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.1 (Nov-2021) ---- '''mupdf::widget 2.1''' '''MuPDFWidget''' ''A basic PDF-viewer widget'' a basic PDF-viewer widget **SYNOPSIS** package require '''Tk 8.6''' package require '''mupdf::widget ?2.1?''' * '''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'''. '''-xscrollcommand''': '''-yscrollcommand''': '''-xscrollincrement''': '''-yscrollincrement''': Same as the standard options to communicate with '''scrollbar'''s **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_add''' ''type'' ''color'': This method could be used only after receiving the event '''<>'''. 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 '''<>''' 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 '''<>''' 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 +. ***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 { %W zoomfit xy } ====== Change the page using the PageUp, PageDown keys ====== bind MuPDFWidget { %W nextpage } bind MuPDFWidget { %W prevpage } ====== **VIRTUAL EVENTS** MUPDFWidget defines a few virtual events for the purposes of notification. * Any time the widget is resized, the virtual event '''<>''' will be generated. * Any time the current page is changed, the virtual event '''<>''' 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 '''<>''' 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 '''<>''' will be generated. **BUGS, IDEAS, FEEDBACK** * - **KEYWORDS** PDF, Snit, widget **CATEGORY** widgets **COPYRIGHT** Copyright (c) 2021, by A.Buratti <> <> PDF | Graphics