org.gicentre.utils.gui

## Class TextPopup

- java.lang.Object
- - org.gicentre.utils.gui.TextPopup

-     public class TextPopup
      extends java.lang.Object

  Creates a popup window for displaying text over a given sketch. Can be used for creating information and help screens. See also `HelpScreen` for keyboard shortcut type help screens.
  Version:
    3.4, 5th February, 2016.
  Author:
    Jo Wood, giCentre, City University London.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `TextPopup(processing.core.PApplet sketch)` Initialises the text popup with default border size and font, but does not display it [requires `setIsActive(true)`].
    `TextPopup(processing.core.PApplet sketch, int xBorder, int yBorder)` Initialises the text popup with default border size and font, but does not display it [requires `setIsActive(true)`].
    `TextPopup(processing.core.PApplet sketch, processing.core.PFont font, int xBorder, int yBorder)` Initialises the text popup with default border size and the given font, but does not display it [requires `setIsActive(true)`].

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addText(java.lang.String textLine)` Adds a given line of text to that displayed in the popup window
    `void` | `addText(java.lang.String textLine, float lineTextSize)` Adds a given line of text to that displayed in the popup window
    `void` | `clearText()` Clears the text to be displayed in the popup window.
    `void` | `draw()` Draws the text in the popup window.
    `java.awt.Dimension` | `getExternalMargin()` Reports the external margins between the popup and the sketch.
    `java.awt.Dimension` | `getInternalMargin()` Reports the internal margins between the popup and the text displayed within it.
    `boolean` | `getIsActive()` Reports whether or not the popup is currently active.
    `float` | `getTextSize()` Reports the current text size in pixels.
    `void` | `setBackgroundColour(int bgColour)` Sets the background colour of the popup.
    `void` | `setExternalMargin(int xMargin, int yMargin)` Sets the external margin between the popup and the edge of the sketch.
    `void` | `setForegroundColour(int fgColour)` Sets the foreground colour of the popup.
    `void` | `setInternalMargin(int xMargin, int yMargin)` Sets the internal margins between the popup and the text displayed within it.
    `void` | `setIsActive(boolean isActive)` Determines whether or not the popup should be currently active.
    `void` | `setText(java.lang.String text)` Replaces the text to be displayed in the popup window with the given text.
    `void` | `setText(java.lang.String text, float textSize)` Replaces the text to be displayed in the popup window with the given text at the given size.
    `void` | `setTextSize(float textSize)` Sets the current text size in pixels.

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

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

- - ### Constructor Detail

    - #### TextPopup

          public TextPopup(processing.core.PApplet sketch)

      Initialises the text popup with default border size and font, but does not display it [requires `setIsActive(true)`].
      Parameters:
        `sketch` - Sketch that will use the popup window.

    - #### TextPopup

          public TextPopup(processing.core.PApplet sketch,
                           int xBorder,
                           int yBorder)

      Initialises the text popup with default border size and font, but does not display it [requires `setIsActive(true)`]. The border defines the number of pixels from within the given sketch, the window is drawn. So border values of 0 would take up the entire sketch, a border value of 10 would leave a 10 pixel wide band of the original sketch visible behind the popup.
      Parameters:
        `sketch` - Sketch that will use the text popup.
        `xBorder` - Width in pixels of the border to the left and right of the popup.
        `yBorder` - Height in pixels of the border to the top and bottom of the popup.

    - #### TextPopup

          public TextPopup(processing.core.PApplet sketch,
                           processing.core.PFont font,
                           int xBorder,
                           int yBorder)

      Initialises the text popup with default border size and the given font, but does not display it [requires `setIsActive(true)`]. The border defines the number of pixels from within the given sketch, the window is drawn. So border values of 0 would take up the entire sketch, a border value of 10 would leave a 10 pixel wide band of the original sketch visible behind the popup.
      Parameters:
        `sketch` - Sketch that will use the text popup.
        `font` - Font used for display of text.
        `xBorder` - Width in pixels of the border to the left and right of the popup.
        `yBorder` - Height in pixels of the border to the top and bottom of the popup.

  - ### Method Detail

    - #### draw

          public void draw()

      Draws the text in the popup window. This method should be called at the end of the Processing sketch's own `draw()` method. If the text popup is not active, nothing will be drawn, if it is active, this popup will be drawn over the top of the sketch that called it.

    - #### getIsActive

          public boolean getIsActive()

      Reports whether or not the popup is currently active. An active popup is one that is displayed in the current sketch.
      Returns:
        True if the popup is active.

    - #### setIsActive

          public void setIsActive(boolean isActive)

      Determines whether or not the popup should be currently active. An active popup is one that is displayed in the current sketch.
      Parameters:
        `isActive` - If true, the popup is made active.

    - #### getTextSize

          public float getTextSize()

      Reports the current text size in pixels.
      Returns:
        Current text size in pixels.

    - #### setTextSize

          public void setTextSize(float textSize)

      Sets the current text size in pixels.
      Parameters:
        `textSize` - New text size in pixels.

    - #### setBackgroundColour

          public void setBackgroundColour(int bgColour)

      Sets the background colour of the popup.
      Parameters:
        `bgColour` - Background colour expressed as a Processing integer colour.

    - #### setForegroundColour

          public void setForegroundColour(int fgColour)

      Sets the foreground colour of the popup. This is the colour of the text displayed and the border around the popup.
      Parameters:
        `fgColour` - Foreground colour expressed as a Processing integer colour.

    - #### setExternalMargin

          public void setExternalMargin(int xMargin,
                                        int yMargin)

      Sets the external margin between the popup and the edge of the sketch. This will cap values between 0 and the half the width or height of the sketch.
      Parameters:
        `xMargin` - Width in pixels of the margin between the left and right of the popup and the sketch.
        `yMargin` - Height in pixels of the margin between the top and bottom of the popup and the sketch.

    - #### getExternalMargin

          public java.awt.Dimension getExternalMargin()

      Reports the external margins between the popup and the sketch.
      Returns:
        Width and height in pixels of the margin between the popup and the sketch.

    - #### setInternalMargin

          public void setInternalMargin(int xMargin,
                                        int yMargin)

      Sets the internal margins between the popup and the text displayed within it.
      Parameters:
        `xMargin` - Width in pixels of the margin between the left and right of the popup and the text.
        `yMargin` - Height in pixels of the margin between the top and bottom of the popup and the text.

    - #### getInternalMargin

          public java.awt.Dimension getInternalMargin()

      Reports the internal margins between the popup and the text displayed within it.
      Returns:
        Width and height in pixels of the margin between the popup and the text.

    - #### addText

          public void addText(java.lang.String textLine)

      Adds a given line of text to that displayed in the popup window
      Parameters:
        `textLine` - Line of text to add.

    - #### addText

          public void addText(java.lang.String textLine,
                              float lineTextSize)

      Adds a given line of text to that displayed in the popup window
      Parameters:
        `textLine` - Line of text to add.
        `lineTextSize` - Vertical size in pixels of text for this line.

    - #### setText

          public void setText(java.lang.String text)

      Replaces the text to be displayed in the popup window with the given text.
      Parameters:
        `text` - New text to display in the popup window.

    - #### setText

          public void setText(java.lang.String text,
                              float textSize)

      Replaces the text to be displayed in the popup window with the given text at the given size.
      Parameters:
        `text` - New text to display in the popup window.
        `textSize` - Vertical size in pixels of text for this line.

    - #### clearText

          public void clearText()

      Clears the text to be displayed in the popup window.