[ABU] 06-mar-2017 ***mupdf::widget*** is a fully customizable widget for displaying PDF-files, based on the package [tclMuPdf], a tcl-binding of the popular MuPDF framework. ***Download *** * [https://sourceforge.net/projects/irrational-numbers/files/MuPdfWidget.zip/download] Pure-tcl package including a small demo <> Reference manual '''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 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: ''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 occurrencies 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 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 { %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