org.faceless.pdf2.viewer2.feature

## Class TextHighlighter

- java.lang.Object
- - org.faceless.pdf2.viewer2.ViewerFeature
  - - org.faceless.pdf2.viewer2.feature.TextHighlighter

- All Implemented Interfaces:
    DocumentPanelListener, PagePanelListener

      public class TextHighlighter
      extends ViewerFeature
      implements DocumentPanelListener, PagePanelListener

  A feature that allows the highlighting of text in the viewer. This takes a fairly simplistic approach, allowing words to be matched manually via the `addWord(java.lang.String)` method, or to a regular expression via the `setPattern(java.util.regex.Pattern)` method. A highlight will then be applied whenever a page containing that word is displayed.

  The `SearchPanel` has similar functionality but takes a more integrated approach, using the `TextTool` to highlight text. Although both `TextTool` and this class can be used to highlight text matching a regular expression, this class does not allow you to copy the selected text to the clipboard. This difference means the selection can be done page by page, whereas TextTool has to extract all the text from the document first.

  Given the non-interactive nature of this class it's likely that this class will be used in a more standalone environment. Here's an example of how to do this:

         Pattern pattern = Pattern.compile("(apples|oranges|[a-z]*berries)");
         TextHighlighter hl = new TextHighlighter();
         hl.setPattern(pattern);
         final Collection<ViewerFeature> features = new ArrayList(ViewerFeature.getAllFeatures());
         features.add(hl);
         SwingUtilities.invokeLater(new Runnable() {
           void run() {
             PDFViewer viewer = PDFViewer.newPDFViewer(features);
             viewer.loadPDF(new File("CropReport.pdf"));
           }
         });
       }

  The following initialization parameters can be specified to configure this feature.

  highlightColor | A 32-bit color value, eg 0x80FF0000 (for translucent red)
  highlightType | One of `block`, `underline`, `outline`, `doubleunderline`, `strikeout` or `doublestrikeout`
  highlightMargin | A floating point value >= 0
  highlightMargin | A floating point value >= 0

  Here's an example showing how to set those attributes in an applet.

       <applet code="org.faceless.pdf2.viewer2.PDFViewerApplet" name="pdfapplet" archive="bfopdf.jar" mayscript>
          <param name="feature.TextHighlighter.highlightColor" value="#FF0000" />
          <param name="feature.TextHighlighter.highlightType" value="strikeout" />
          <param name="feature.TextHighlighter.pattern" value="(apples|oranges|[a-z]*berries)" />
       </applet>

  or when running as an Application:

       java -Dorg.faceless.pdf2.viewer2.TextHighlighter.word0=apples \
            -Dorg.faceless.pdf2.viewer2.TextHighlighter.word1=oranges \
            -jar bfopdf.jar

  The name of this feature is TextHighlighter

  This code is copyright the Big Faceless Organization. You're welcome to use, modify and distribute it in any form in your own projects, provided those projects continue to make use of the Big Faceless PDF library.

  Since:
    2.8.1
  See Also:
    `SearchPanel`, `SearchField`, `TextTool`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `TextHighlighter()` Create a new TextHighlighter

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addWord(String word)` Add a word to highlight to this TextHighlighter.
    `void` | `documentUpdated(DocumentPanelEvent event)` Called when an `DocumentPanelEvent` is raised
    `void` | `initialize(PDFViewer viewer)` Called when the feature is first added to a viewer
    `void` | `pageUpdated(PagePanelEvent event)` Called when a `PagePanelEvent` is raised
    `void` | `setHighlightType(int type, Paint paint, Stroke stroke, float margin)` Set the type of Highlight to use.
    `void` | `setPattern(Pattern pattern)` Set the Regular Expression used to determine which words to highlight.

    - ### Methods inherited from class org.faceless.pdf2.viewer2.ViewerFeature

      `getAllEnabledFeatures, getAllFeatures, getCustomJavaScript, getFeatureProperty, getFeatureURLProperty, getName, isEnabledByDefault, setFeatureName, teardown, toString`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### TextHighlighter

          public TextHighlighter()

      Create a new TextHighlighter

  - ### Method Detail

    - #### setPattern

          public void setPattern(Pattern pattern)

      Set the Regular Expression used to determine which words to highlight. Calling this method will cause any words added by the `addWord(java.lang.String)` method to be ignored - you should call one or the other, not both.
      Parameters:
        `pattern` - the Pattern to match, or `null` to match whataver words have been added via `addWord(java.lang.String)`
      Since:
        2.11

    - #### addWord

          public void addWord(String word)

      Add a word to highlight to this TextHighlighter. For more than a couple of words it's likely to be more efficient to call `setPattern(java.util.regex.Pattern)`, and this is the approach we recommend for new implementations.
      Parameters:
        `word` - the new word to highlight if found

    - #### initialize

          public void initialize(PDFViewer viewer)

      Description copied from class: `ViewerFeature`
      Called when the feature is first added to a viewer
      Overrides:
        `initialize` in class `ViewerFeature`

    - #### documentUpdated

          public void documentUpdated(DocumentPanelEvent event)

      Description copied from interface: `DocumentPanelListener`
      Called when an `DocumentPanelEvent` is raised
      Specified by:
        `documentUpdated` in interface `DocumentPanelListener`

    - #### setHighlightType

          public void setHighlightType(int type,
                                       Paint paint,
                                       Stroke stroke,
                                       float margin)

      Set the type of Highlight to use.
      Parameters:
        `type` - one of `TextTool.TYPE_BLOCK`, `TextTool.TYPE_OUTLINE`, `TextTool.TYPE_UNDERLINE`, `TextTool.TYPE_DOUBLEUNDERLINE`, `TextTool.TYPE_STRIKEOUT` or `TextTool.TYPE_DOUBLESTRIKEOUT`
        `paint` - the paint to use - must not be null. For `TextTool.TYPE_BLOCK` highlights this color will typically be translucent.
        `stroke` - the stroke to use for outline or underlining, or `null` to choose automatically. Not used with `TextTool.TYPE_BLOCK`.
        `margin` - how many points around the text to use as a margin.

    - #### pageUpdated

          public void pageUpdated(PagePanelEvent event)

      Description copied from interface: `PagePanelListener`
      Called when a `PagePanelEvent` is raised
      Specified by:
        `pageUpdated` in interface `PagePanelListener`

Copyright © 2001-2015 Big Faceless Organization