org.gicentre.utils.text

## Class WordWrapper

- java.lang.Object
- - org.gicentre.utils.text.WordWrapper

-     public class WordWrapper
      extends java.lang.Object

  This class provides a some static methods for wrapping text giving more control to how it is displayed that Processing's built-in functions
  Version:
    3.4, 5th February, 2016.
  Author:
    Aidan Slingsby, giCentre, City University London.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `WordWrapper()`

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static java.util.List<java.lang.String>` | `wordWrap(java.lang.String text, int width, processing.core.PApplet sketch)` Works out where a string of text needs to wrap to fit into a given width in pixels and returns as a list of strings, each of which will not exceed the given width.
    `static java.util.List<java.lang.String>` | `wordWrap(java.lang.String textToWrap, int width, processing.core.PGraphics pGraphics)` Works out where a string of text needs to wrap to fit into a given width in pixels and returns as a list of strings, each of which will not exceed the given width.
    `static java.util.List<WrappedToken>` | `wordWrapAndTokenise(java.lang.String text, float x, float y, float width, processing.core.PApplet sketch)` Tokenises the input string and return a list of these tokens and where they should be drawn.
    `static java.util.List<WrappedToken>` | `wordWrapAndTokenise(java.lang.String textToTokenize, float x, float y, float width, processing.core.PGraphics pGraphics)` Tokenises the input string and return a list of these tokens and where they should be drawn.

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

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

- - ### Constructor Detail

    - #### WordWrapper

          public WordWrapper()

  - ### Method Detail

    - #### wordWrap

          public static java.util.List<java.lang.String> wordWrap(java.lang.String text,
                                                                  int width,
                                                                  processing.core.PApplet sketch)

      Works out where a string of text needs to wrap to fit into a given width in pixels and returns as a list of strings, each of which will not exceed the given width. The advantage over using Processing's draw(text,x,y,w,h) is that the number of lines that result is known.
      `\t` characters are converted to single spaces
      `\n` are honoured
      Uses the sketch's current `textFont` and `textSize`. Wraps on '`` ' and '`-`'.
      Parameters:
        `text` - Text to wrap
        `width` - Width to wrap text to
        `sketch` - The sketch (uses current font)
      Returns:
        List of lines that will not exceed width

    - #### wordWrap

          public static java.util.List<java.lang.String> wordWrap(java.lang.String textToWrap,
                                                                  int width,
                                                                  processing.core.PGraphics pGraphics)

      Works out where a string of text needs to wrap to fit into a given width in pixels and returns as a list of strings, each of which will not exceed the given width. The advantage over using Processing's draw(text,x,y,w,h) is that the number of lines that result is known.
      `\t` characters are converted to single spaces
      `\n` are honoured
      Uses `pGraphics`'s current `textFont` and `textSize`. Wraps on '`` ' and '`-`'.
      Parameters:
        `textToWrap` - Text to wrap.
        `width` - Width to wrap text to.
        `pGraphics` - The graphic context doing the text drawing.
      Returns:
        List of lines that will not exceed width.

    - #### wordWrapAndTokenise

          public static java.util.List<WrappedToken> wordWrapAndTokenise(java.lang.String text,
                                                                         float x,
                                                                         float y,
                                                                         float width,
                                                                         processing.core.PApplet sketch)

      Tokenises the input string and return a list of these tokens and where they should be drawn. Wraps text to the given width and tokenises the string according to the token information embedded and so that tokens do not run over multiple lines.
      Designed for:
      - colouring different words/phrases in a paragraph in different colours
      - facilitating mouse interaction with words/phrase inline in a paragraph
      Embedded token information takes the form of a string in curly brackets inline in the supplied text. The string identifies the token in the return WrappedTokens.
      For example:
      `"{other}The {adjective}quick{other} {adjective}brown{other} fox jumped over the {adjective}lazy{other} dog"`
      results in a series of tokens that do not straddle lines and are identified as "other" or "adjective". Any strings can be used.
      The WrappedTokens returned contain the required information to draw them in the correct place on the screen.
      Wraps on '`` ' and '`-`'. Uses the sketch's current `textFont`, `textSize`, `textLeading` (line spacing) and `textAlign`. The token positions returned can be used directly in the PApplet's `text(text,x,y)` method.
      Parameters:
        `text` - The text to tokenise.
        `x` - The x position of the text block placement.
        `y` - The y position of the text block placement.
        `width` - The width of the area within which to wrap text.
        `sketch` - The sketch doing the text drawing.
      Returns:
        List of `WrappedToken`s that contain the information required to display these on screen.

    - #### wordWrapAndTokenise

          public static java.util.List<WrappedToken> wordWrapAndTokenise(java.lang.String textToTokenize,
                                                                         float x,
                                                                         float y,
                                                                         float width,
                                                                         processing.core.PGraphics pGraphics)

      Tokenises the input string and return a list of these tokens and where they should be drawn. Wraps text to the given width and tokenises the string according to the token information embedded and so that tokens do not run over multiple lines.
      Designed for:
      - colouring different words/phrases in a paragraph in different colours
      - facilitating mouse interaction with words/phrase inline in a paragraph
      Embedded token information takes the form of a string in curly brackets inline in the supplied text. The string identifies the token in the return WrappedTokens.
      For example:
      `"{other}The {adjective}quick{other} {adjective}brown{other} fox jumped over the {adjective}lazy{other} dog"`
      results in a series of tokens that do not straddle lines and are identified as "other" or "adjective". Any strings can be used.
      The WrappedTokens returned contain the required information to draw them in the correct place on the screen.
      Wraps on '`` ' and '`-`'. Uses the `pGraphics`'s current `textFont`, `textSize`, `textLeading` (line spacing) and `textAlign`. The token positions returned can be used directly in the PApplet's `text(text,x,y)` method.
      Parameters:
        `textToTokenize` - The text to tokenise.
        `x` - x position of the text placement.
        `y` - y position of the text placement.
        `width` - Width within to wrap text.
        `pGraphics` - Graphics context doing the text drawing.
      Returns:
        List of WrappedTokens that contain the information required to display these on screen