(PDF)Filter ver. 1.5,
Written by Vladimir Olovyannikov;
e-mail:volovyan@gmail.com
----------------------------------

ABSTRACT

(PDF)filter plugin was developed as an agent between TC's Lister 
and application capable to convert files of one type to another. 
There are actually two reasons I wrote it.

The first and the main one is that I wanted to get general understanding 
of TC's Lister plugin implementation.
However, when I was just thinking about it, I had to roghly view a dozen 
of PDFs on the computer. The basic task when vieweing of a PDF file is the 
TEXT available in the PDF document. However, sometimes PDFs are just converted images, 
and therefore, do not contain text at all. Based on these issues, 
the (PDF)filter plugin has been "born". 
This is my first plugin for TC.

DESCRIPTION

Unlike present PDFView plugin I tried to use (Thanks to his author for the plugin),
the filter (I would prefer to call it so) is capable to convert arbitrary file from 
one format to text, picture (BMP, GIF, or JPG), and HTML, via appropriate converter
or using an appropriate ActiveX by MSHTML object. Multiple instances of Lister windows 
using the MSHTML ActiveX are supported as well.

To obtain TEXT from a PDF, I would suggest to use XPDF (http://www.foolabs.com/xpdf/) 
and pdftotext program which uses XPDF library. Most of documents I had to work with 
were in English, and therefore I didn't have a problem. Until a document in cyrillic 
encountered. Fortunately, XPDF provides ability to explicitly specify encoding in 
command line, so the issue was solved easily. The plugin converts KOI8 text to ANSI 
automatically (as far as I know, only KOI8-R package is availble for cyrillic so far
for XPDF). Two files required for cyrillic are: Bulgarian.nameToUnicode and 
KOI8-R.unicodeMap.

There is a program called pdftohtml, which converts PDF format to HTML-one, and which uses
XPDF as well. Its homesite is http://pdftohtml.sourceforge.net.

To convert a PDF file into a picture Ghostscript interpreter can be used. However, I found that
sometimes Pdf2Bmp produces better output though it uses GS.

Personally, I would highly recommend pdftotext to obtain text only for lightning-fast
conversion.


FEATURES

- Ability to display arbitrary file converted by a converter specified in the 
  listfilter.ini file (see below).
- Ability to switch between converters available for the file (see above).
- Ability to use MSHTML to render the file with assigned ActiveX
- Ability to search within a file if there is at least one converter able to convert from an 
  arbitrary file format to text format is specified.
- Ability to display a picture of converted page  
- Entire file is converted only for search within the document, otherwise, page-by-page 
  conversion is used.
- Mouse wheel movement is supported both for TEXT and PICTURE formats, as well as all cursor keys, 
  thus  making an illusion of "continuous" document.
- It is possible to go to a certain page of a document.
- Ability to increase/decrease picture size (+ and - keys) as well as setting of an arbitrary 
  picture viewing size. Ability to make the picture fit width, fit height, or fit page.
- Ability to capture stdout and show console and execution window (adjusted via listfilter.ini file)
- More... (see History below)


DISCLAIMER
 The plugin is provided AS IS with no warranty of any kind. Use at your own risk.

REQUIREMENTS

 1. Total Commander 5.51 or higher (ver. 6.5 or higher for WDX searches and thumbnails support).
 2. Converters (file-format->txt,bmp, or htm*). The converter MUST have command line parameters to be 
    invoked by the plugin. If a converter does not have an option to convert a single page, then all pages are converted.
    
INSTALLATION

 1. Create a directory for the plugin under the TC's Plugins Directory, e.g. PDFFilter
 2. Unzip the archive with plugin to the directory created
 3. Go to menu Configuration -> Options -> Edit/View -> Configure Internal Viewer->LS Plugins
 3. Click "Add"
 4. Go to the directory, where you have you archvie unzipped, and select filter.wlx
 5. Click OK. You can now view the files via the plugin if you have a converter available specified in the 
    listfilter.ini file.
 Optional: to have the plugin to help TC to search in supported files, add the same plugin to WDX plugins (no need to create any other folders,
 just specify the one you installed the lister's plugin folder into.
    
LISTFILTER.INI LOCATION

 Since version 1.01 the configuration file listfilter.ini can be placed anywhere. Skip this paragraph if you don't 
 wish to change its' location, which is default to plugin's folder.
 If it is desired to place listfilter.ini to another location, please do the following:
 a. Open the lsplugin.ini for editing (this file is located in the TC's directory)
 b. Create a section named PDFFilter (case insensitive)->[PDFFilter]
 c .Type the following under that section: IniDir=%TC% if you wish to have your listfilter.ini file in the same
    folder as lsplugin.ini, or, otherwise, type the path where the listfilter.ini can be found by the plugin. 
    If you wish to make plugin to read the listfilter.ini file from its' own directory, just remove either the PDFFilter
    section or IniDir parameter.
 Beginning from ver. 1.5 of the plugin, any listfilter.ini can be used. To have plugin to read any other listfilter.ini, specify
 IniName=path_and_name_to_the_desired_config_file in the [General] section of the listfilter.ini.

OPERATION

 When the plugin is invoked, it reads plugin's listfilter.ini file to find a section with the same name as the 
 file extension. It then transfers control to TC if no match found, or uses those entries from
 the section mentioned. The file listfilter.ini shipped with the plugin is self-explanatory and contains several
 filters I use most of all. For me, the plugins serves as Txt,Picture and HTML viewer for PDF, PS, EPS, and many others.
 
 HOTKEYS AVAILABLE
 
 - All Lister's hotkeys are allowed
 - To switch pages the following keys are used:
   < - go to previous page;
   > - go to next page
   PgUp/PgDn - Ususal Page Up/Down for all modes except for image: for image mode these keys
   play the same role as < and >.
 
 
 HISTORY
 Legend:
 +=new feature
 !=bug fix
 01 March, 2004 
 Initial release, version 1.0
 
 05 March, 2004 - 
 
 +Ability to print content
 !several minor bugs
 
 12 March, 2004 
 +Ability to set listfilter.ini in an arbitrary folder
 +Description feature (see listfilter.ini for details), 
 !minor bug with stdout capturing
 
 14 March, 2004 
 +Save Page content feature
 +Font selection for text viewer
 +Optional: Load page when up/down buttons of page selector are clicked
 +"Page" button:
    allows going to selected page by clicking;
    has own popup menu, allowing converting of the whole document 
    for text and HTML.
 !Plugin erroneousely was sending numpad numeric keys to Lister,
 instead of scale/current page selector changing, when a user was typing
 in the fields mentioned, which lead to unavailability of numeric keypad to
 type in Page selector and Scale fields.
 
 15 March, 2004
 +Ability to swap page selector buttons (for those using the feature "loading page when up/
 down buttons of page selector are clicked) - see listfilter.ini, ReverseUpDown option
 +Having detected the "feature" of gswin32c with PS-files (only the first page is converted)
  new way of PS-file conversion used: see the [PS] section of the listfilter.ini, Format_BMP with gswin32c
 !In picture mode: if a page has been scrolled, and then another page number was requested through the page selector,
  that page was also scrolled to that amount of pixels.
 
 17 March, 2004
  !Bug with scrollthumb movements, thanks to mik
  !+Minor adjustments
 
 18 March, 2004
  +Due to a huge number of requests, the feature of copying the file to be viewed 
  to the Temp directory (for non-English users using converters which cannot work 
  with folder/files containing national alphabet characters).
  +Ability to use picture converters, converting file to jpeg (JPG)-experimental (many users requested that). 
  This is especially useful for gswin32c ver. 8.0 and higher, which supports anti-aliasing.
 
 24 March, 2004
 +readme_details_eng.txt - detail description of filter plugin in English is available
 +Multifile/multifolder search for supported extensions (see below)
 !Minor jpeg issues
  
 19 April, 2004
  +ability to specify %tc% (case sensitive) as a folder for Entries. 
   This will be substituted with TC's folder by plugin. (Suggested by Dmitry)
   
 05 May, 2004
  +ability to output debug information via OutputDebugString
  +ability to switch off insertion of a PDF ActiveX control
  +ability to increase/decrease RESOLUTION for pictures (tested with gswin32 and pdf2bmp).
   Do not mess the RESOLUTION and ZOOM factor: each clicking of the "Increase/decrease resolution" 
   results in the current page is CONVERTED with specified resolution, whereas ZOOM factor just zoomes in/out
   of the image which has been obtained since the last conversion.
   The increase/decrease resolution works only if either %resx%, %resy%, or %res% placeholder is specified somewhere
   inside the format string.
   Hotkeys for increasing/decreasing RESOLUTION are:
     Ctrl+GrayPlus - increases the resolution by 10;
     Ctrl+GrayMinus - decreases the resolution by 10.
    Applied only for those entries which contain %res%/%resx%/%resy% placeholders.
    The changed resolution will apply to the whole session of the current document view using the 
    current converter.
    PS. Shift and Alt keys may also be used in combination with Grayplus/GrayMinus for the same operations,
    that is Shift+GrayPlus is the same as Ctrl+GrayPlus.
  +ability to scroll picture horizontally and vertically via keyboard cursor keys
 
 10 May, 2004
 +"Convert all pages" now works when viewing a document as an image
 
 06 June, 2004
 + The plugin can now print a range of pages rather than the current one for image content. 
   Use "Print->Range..." (Ctrl-Shift-R shortcut) option for that. This option for printing graphics was introduced  because sometimes Acrobat Reader cannot render content either as "Print as graphics", or not. I encountered a problem when trying to print the United Kingdom Visa Application form obtained from UK site.
 + Due to numerous requests from plugin's users I have compiled an "add-on" for the Filter - Converters' pack, which is not part of this download due to its size.
 
 18 January, 2005
 + Image can now be rotated
 + PDF filter configuration tool is now available to edit listfilter.ini config. file (separate download)
   The plugin allow invoke it if available.
 ! Eliminated PDF activeX control "injection" for PDF files, thus loading process speeds up.
 ! A lot of bugs fixed.
 
24 April, 2005
 + MSHTML ActiveX is used instead of only Acrobat PDF control - this allows rendering of arbitrary 
  file via MSHTML-ActiveX, and not only PDF.
 + Bugs fixed. 

26 May, 2006
 +Printing module rewritten from scratch
 !Detected bugs fixed
 +Minor improvements

11 July, 2006
 +New substitution %i% to ignore output directory for converters, thanks to Matthias 
  which do not recognize destination options and do not produce stdout output (like flare). Now those
  converters are also supported.

12 December 2009
 +Plugin is now capable to work as WDX plugin to search text with the means of TC in all supported files
 +Plugins is now capable to transfer thumbnails to TC on TC request for all supported files (see listfilter.txt for details)
  (use TC's menu item "View- Show thumbnails" to activate thumbnails view)
 +Plugin's logging can be set to "no logging", "brief", "details" and "all" to facilitate problems solving if any
 !It is now possible to use Up-Dn and PgUp-PgDn buttons to switch pages in HTML view.
 !The last part of the standard output was sometimes missing after conversion
 !Some issues with image viewing using keyboard
 !!Fixed potential issue of deletion of the folder being searched by internal plugin's search feature
 !Memory leaks
 !Plugin's crash in non-standard situations
 !Vast amount of small fixes

5 April 2010
 +Added internal functions to allow format lines testing from within Multilister Configuration Tool 2.0
 
Your comments are welcome.

PS


Vladimir Olovyannikov.
e-mail: volovyan@gmail.com