org.faceless.pdf2.viewer2.feature

## Class TextTool

- java.lang.Object
- - org.faceless.pdf2.viewer2.ViewerFeature
  - - org.faceless.pdf2.viewer2.ViewerWidget
    - - org.faceless.pdf2.viewer2.ToggleViewerWidget
      - - org.faceless.pdf2.viewer2.feature.TextTool

- All Implemented Interfaces:
    FocusListener, PropertyChangeListener, EventListener, DocumentPanelListener, PagePanelInteractionListener, PagePanelListener

      public class TextTool
      extends ToggleViewerWidget
      implements DocumentPanelListener, PagePanelInteractionListener, PagePanelListener, FocusListener, PropertyChangeListener

  This widget allows text to be selected from the DocumentViewport. By default it uses a translucent yellow highlight, but this can be set using the `setHighlightType()` method or the matching initialization parameters. When the text is highlighted, right-clicking on the page will bring up a list of any `TextSelectionAction` features specified in the viewer.

  The TextTool object selects text in a document-wide manner, not just from the currently visible pages (which was the behaviour prior to 2.11.7). This means operations like `selectAll()` or `select(Pattern)` require all the text in the PDF to be extracted, which can cause these two operations to take some time to complete. One solution is to add the `BackgroundTextExtractor` feature, which will automatically begin the text extaction when a PDF is loaded.

  The `TextHighlighter` class performs a similar job, except no mouse selection or no copying to the clipboard is possible. These differences mean if you simply want to highlight text matching a pattern, this class will have to extract text from the entire PDF first, whereas that class will do it on a page by page basis.

  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
  draggable | `true` or `false`, for `setDraggable(boolean)`
  selectPattern | A `java.util.regex.Pattern` to be searched for automatically when a PDF is loaded
  selectTextToolOnTextSelection | if specified, toggle text selection mode in the viewer when text is selected by other means (e.g. clicking a search result)
  selectionOrder | `display` or `natural`, to set the order text is selected in when dragging the mouse. Defaults to "natural".

  The name of this feature is TextTool

  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.5
  See Also:
    `TextSelectionAction`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `TYPE_BLOCK` A parameter to `setHighlightType(int, java.awt.Paint, java.awt.Stroke, float)` which will highlight the selected text using a solid block of (usually translucent) color
    `static int` | `TYPE_DOUBLESTRIKEOUT` A parameter to `setHighlightType(int, java.awt.Paint, java.awt.Stroke, float)` which will strike-out the selected text with a double line
    `static int` | `TYPE_DOUBLEUNDERLINE` A parameter to `setHighlightType(int, java.awt.Paint, java.awt.Stroke, float)` which will highlight the selected text using a double underline.
    `static int` | `TYPE_OUTLINE` A parameter to `setHighlightType(int, java.awt.Paint, java.awt.Stroke, float)` which will outline the selected text.
    `static int` | `TYPE_STRIKEOUT` A parameter to `setHighlightType(int, java.awt.Paint, java.awt.Stroke, float)` which will strike-out the selected text.
    `static int` | `TYPE_UNDERLINE` A parameter to `setHighlightType(int, java.awt.Paint, java.awt.Stroke, float)` which will highlight the selected text using a single underline.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TextTool()` Create a new TextTool object

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `action(ViewerEvent event)` Toggle the active state of this widget by calling `ToggleViewerWidget.setSelected(boolean)`
    `void` | `clear()` Deselect all the text on the viewport
    `void` | `copy()` Copy the selected text (if any) to the System clipboard
    `void` | `documentUpdated(DocumentPanelEvent event)` Called when an `DocumentPanelEvent` is raised
    `void` | `focusGained(FocusEvent event)`
    `void` | `focusLost(FocusEvent event)`
    `TextSelection.RangeList` | `getRangeList()`
    `void` | `initialize(PDFViewer viewer)` Called when the feature is first added to a viewer
    `void` | `pageAction(PagePanelInteractionEvent event)` Handle mousePressed, mouseDragged and mouseMoved events on this page, which are used to select text.
    `void` | `pageUpdated(PagePanelEvent event)` Called when a `PagePanelEvent` is raised
    `void` | `propertyChange(PropertyChangeEvent event)`
    `void` | `select(Collection<PageExtractor.Text> texts)` Select the specified text objects.
    `void` | `select(PageExtractor.Text text)` Select the specified text.
    `void` | `select(Pattern pattern)` Select any text matching the specified Pattern.
    `void` | `selectAll()` Select all the text in the currently displayed viewport.
    `void` | `setDraggable(boolean draggable)` Set whether this TextTool can select text by dragging over it.
    `void` | `setHighlightType(int type, Paint paint, Stroke stroke, float margin)` Set the type and color of the highlight.
    `void` | `setOrder(Comparator<PageExtractor.Text> order)` Set the order in which text is selected in this TextTool, either `PageExtractor.NATURALORDER` or `PageExtractor.DISPLAYORDER`.
    `protected void` | `updateViewport(DocumentViewport viewport, boolean selected)` Called from `ToggleViewerWidget.setSelected(boolean)`, this method is called in each viewport in use by the `PDFViewer` or `DocumentPanel` so it can update its status.

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

      `getGroupName, getGroupOwner, getGroupSelection, getWidgets, isSelected, setGroupOwner, setSelected`

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

      `createActionListener, getComponent, getIcon, getViewer, isButtonEnabledByDefault, isDocumentRequired, isMenuEnabledByDefault, setButton, setComponent, setDocumentRequired, setMenu, setMenu, setToolBarEnabled, setToolBarEnabledAlways, setToolBarFloatable, setToolBarFloating, toString`

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

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

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

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

- - ### Field Detail

    - #### TYPE_BLOCK

          public static final int TYPE_BLOCK

      A parameter to `setHighlightType(int, java.awt.Paint, java.awt.Stroke, float)` which will highlight the selected text using a solid block of (usually translucent) color
      See Also:
        Constant Field Values

    - #### TYPE_UNDERLINE

          public static final int TYPE_UNDERLINE

      A parameter to `setHighlightType(int, java.awt.Paint, java.awt.Stroke, float)` which will highlight the selected text using a single underline.
      Since:
        2.11.4
      See Also:
        Constant Field Values

    - #### TYPE_DOUBLEUNDERLINE

          public static final int TYPE_DOUBLEUNDERLINE

      A parameter to `setHighlightType(int, java.awt.Paint, java.awt.Stroke, float)` which will highlight the selected text using a double underline.
      Since:
        2.11.4
      See Also:
        Constant Field Values

    - #### TYPE_OUTLINE

          public static final int TYPE_OUTLINE

      A parameter to `setHighlightType(int, java.awt.Paint, java.awt.Stroke, float)` which will outline the selected text.
      Since:
        2.11.4
      See Also:
        Constant Field Values

    - #### TYPE_STRIKEOUT

          public static final int TYPE_STRIKEOUT

      A parameter to `setHighlightType(int, java.awt.Paint, java.awt.Stroke, float)` which will strike-out the selected text.
      Since:
        2.11.4
      See Also:
        Constant Field Values

    - #### TYPE_DOUBLESTRIKEOUT

          public static final int TYPE_DOUBLESTRIKEOUT

      A parameter to `setHighlightType(int, java.awt.Paint, java.awt.Stroke, float)` which will strike-out the selected text with a double line
      Since:
        2.11.4
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### TextTool

          public TextTool()

      Create a new TextTool object

  - ### Method Detail

    - #### setHighlightType

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

      Set the type and color of the highlight. If drawing a "block", the specified color should be translucent so the text behind it is still visible when selected.
      Parameters:
        `type` - the type of highlight - `TYPE_BLOCK`, `TYPE_OUTLINE`, `TYPE_UNDERLINE`, `TYPE_DOUBLEUNDERLINE`, `TYPE_STRIKEOUT` or `TYPE_DOUBLESTRIKEOUT`
        `paint` - the Paint to paint this highlight with
        `stroke` - the Stroke to stroke this highlight with (not used for `TYPE_BLOCK`)
        `margin` - the distance in points from the text
      Since:
        2.11.4

    - #### setDraggable

          public void setDraggable(boolean draggable)

      Set whether this TextTool can select text by dragging over it. For all TextTool instances that interact with the mouse, this should be set to true (the default)
      Parameters:
        `draggable` - whether this TextTool can select text with the mouse

    - #### setOrder

          public void setOrder(Comparator<PageExtractor.Text> order)

      Set the order in which text is selected in this TextTool, either `PageExtractor.NATURALORDER` or `PageExtractor.DISPLAYORDER`. For documents internally constructed in a logical order, natural is usually the best choice as for text in columns, it will allow you to select an individual column. However there is no way to determine this in advance, so if there's any doubt, then "display" will always give acceptable results. The default is "natural"
      Parameters:
        `order` - the order in which text is selected.
      Since:
        2.12

    - #### 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 `ToggleViewerWidget`

    - #### action

          public void action(ViewerEvent event)

      Description copied from class: `ToggleViewerWidget`
      Toggle the active state of this widget by calling `ToggleViewerWidget.setSelected(boolean)`
      Overrides:
        `action` in class `ToggleViewerWidget`

    - #### getRangeList

          public TextSelection.RangeList getRangeList()

    - #### propertyChange

          public void propertyChange(PropertyChangeEvent event)

      Specified by:
        `propertyChange` in interface `PropertyChangeListener`

    - #### updateViewport

          protected void updateViewport(DocumentViewport viewport,
                                        boolean selected)

      Description copied from class: `ToggleViewerWidget`
      Called from `ToggleViewerWidget.setSelected(boolean)`, this method is called in each viewport in use by the `PDFViewer` or `DocumentPanel` so it can update its status. By default it is a no-op.
      Overrides:
        `updateViewport` in class `ToggleViewerWidget`

    - #### focusGained

          public void focusGained(FocusEvent event)

      Specified by:
        `focusGained` in interface `FocusListener`

    - #### focusLost

          public void focusLost(FocusEvent event)

      Specified by:
        `focusLost` in interface `FocusListener`

    - #### documentUpdated

          public void documentUpdated(DocumentPanelEvent event)

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

    - #### pageUpdated

          public void pageUpdated(PagePanelEvent event)

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

    - #### copy

          public void copy()

      Copy the selected text (if any) to the System clipboard

    - #### selectAll

          public void selectAll()

      Select all the text in the currently displayed viewport. This will cause all the text to be extracted if it hasn't already, which may be a slow operation.

      Any subsequent selections, by the mouse or programatically, will replace this selection.

      See Also:
        `select(Pattern)`, `BackgroundTextExtractor`

    - #### clear

          public void clear()

      Deselect all the text on the viewport
      Since:
        2.10.4

    - #### select

          public void select(PageExtractor.Text text)

      Select the specified text. If the text is on a different page to the current one, the page is changed first, and either way the viewport may be repositioned to display the specified text.

      Any subsequent selections, by the mouse or programatically, will replace this selection.

      Parameters:
        `text` - the Text item to display, or `null` to select no text
      Throws:
        `IllegalArgumentException` - if the text item is from a different PDF to that currently displayed

    - #### select

          public void select(Collection<PageExtractor.Text> texts)

      Select the specified text objects. The viewport will not be scrolled to match the selections, so the text may be from any loaded PDF objects.

      Any subsequent selections, by the mouse or programatically, will replace this selection.

      Parameters:
        `texts` - a Collection of `PageExtractor.Text` objects.
      Since:
        2.11.7
      See Also:
        `TextHighlighter`, `TextSelectionAction`

    - #### select

          public void select(Pattern pattern)

      Select any text matching the specified Pattern. This method has to run a pattern match against the entire PDF in the currently displayed viewport, so if the text has not yet been extracted this method could take some time to complete.

      Any subsequent selections, by the mouse or programatically, will replace this selection.

      See Also:
        `BackgroundTextExtractor`, `PageExtractor.getMatchingText(java.lang.String)`, `TextHighlighter`, `TextSelectionAction`

    - #### pageAction

          public void pageAction(PagePanelInteractionEvent event)

      Handle mousePressed, mouseDragged and mouseMoved events on this page, which are used to select text. Text can be selected by clicking and dragging over it, or by double clicking (to select the current word) or triple clicking (to select the current line)
      Specified by:
        `pageAction` in interface `PagePanelInteractionListener`

Copyright © 2001-2015 Big Faceless Organization