WordCram (WordCram API)

java.lang.Object
- wordcram.WordCram

```
public class WordCram
extends java.lang.Object
```
The main API for WordCram.
There are three steps to making a WordCram:
1. weight your words
2. style your words
3. draw your WordCram
You start with a new WordCram(this), and then...
Step One: Weight Your Words
Give WordCram some text to chew on, or an array of Words you've weighted yourself.
Let WordCram Weight Your Words

WordCram weights your words by the number of times they appear in a document. It can load the document a few ways:
- fromWebPage(String) and fromHtmlFile(String) load the HTML and scrape out the words
- fromHtmlString(String...) takes a String (or String[]), assumes it's HTML, and scrapes out its text
- fromTextFile(String) loads a file (from the filesystem or the network), and counts the words
- fromTextString(String...) takes a String (or String[]), and counts the words
If you need some other way to load your text, pass your own TextSource to fromText(TextSource), and WordCram get its text via TextSource.getText().
Once the text is loaded, you can control how WordCram counts up the words.
Case sensitivity: If your text contains "hello", "HELLO", and "Hello",
- lowerCase() will count them all as "hello"
- upperCase() will count them all as "HELLO"
- keepCase(), the default, will count them separately, as three different words
Numbers: If your text contains words like "42" or "3.14159", you can remove them with excludeNumbers() (the default), or include them with includeNumbers().
Stop words: WordCram uses cue.language to remove common words from the text by default, but you can add your own stop words with withStopWords(String).
Weight Your Own Words

If you have some other way to weight your words, you can pass them to fromWords(Word[]), and in that case, you can use Word.setColor(int), Word.setFont(PFont), Word.setAngle(float), and/or Word.setPlace(PVector) to control how any (or all) of your Words are drawn.
Step Two: Style Your Words
There are six questions you have to answer when drawing a word on the WordCram:
How big should it be?
A word can be sizedByWeight(int, int), sizedByRank(int, int), or withSizer(WordSizer)
How should it be angled?
It can be angledAt(float...), angledBetween(float, float), or withAngler(WordAngler)
What font should it be in?
You can render words withFont(String) or withFonts(String...) (those both can also take PFonts), or withFonter(WordFonter)
How should it be colored?
withColor(int), withColors(int...), or withColorer(WordColorer)
Where on the image should it go?
withPlacer(WordPlacer)
If it doesn't fit at first, how should I nudge it?
withNudger(WordNudger)
Step Three: Draw Your WordCram

After all that, actually rendering the WordCram is simple. You can repeatedly call drawNext() while the WordCram hasMore() words to draw (probably once per Processing frame):
```
 void draw() {
     if (wordCram.hasMore()) {
         wordCram.drawNext();
     }
 }
 
```
Or you can call drawAll() once, and let it loop for you:
```
 void draw() {
     wordCram.drawAll();
 }
 
```
Step Three-and-a-Half: How Did It Go?

If you're having trouble getting your words to show up, you might want to getSkippedWords(). Knowing which words were skipped, and why (see Word.wasSkippedBecause()), can help you size and place your words better.
You can also getWords() to see the whole list, and getWordAt(float,float) to see which word covers a given pixel.

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`NO_SPACE` Skip Reason: WordCram tried placing the Word, but it couldn't find a clear spot.
`static int`	`SHAPE_WAS_TOO_SMALL` Skip Reason: the Word's shape was too small.
`static int`	`WAS_OVER_MAX_NUMBER_OF_WORDS` Skip Reason: the Word was skipped because `maxNumberOfWordsToDraw(int)` was set to some value, and the Word came in over that limit.

Constructor Summary

Constructors
Constructor and Description

WordCram(processing.core.PApplet parent)
Make a new WordCram.

Constructors
Constructor and Description
`WordCram(processing.core.PApplet parent)` Make a new WordCram.

Method Summary

Methods
Modifier and Type	Method and Description
`WordCram`	`angledAt(float... anglesInRadians)` Make the WordCram rotate each word at one of the given angles.
`WordCram`	`angledBetween(float minAngleInRadians, float maxAngleInRadians)` Make the WordCram rotate words randomly, between the min and max angles.
`void`	`drawAll()` Just like it sounds: draw all the words.
`void`	`drawNext()` If the WordCram has any more words to draw, draw the next one.
`WordCram`	`excludeNumbers()` Exclude numbers from the text in the WordCram.
`WordCram`	`fromHtmlFile(java.lang.String htmlFilePath)` Make a WordCram from the text in a HTML file.
`WordCram`	`fromHtmlString(java.lang.String... html)` Makes a WordCram from a String of HTML.
`WordCram`	`fromText(TextSource textSource)` Makes a WordCram from any TextSource.
`WordCram`	`fromTextFile(java.lang.String textFilePathOrUrl)` Makes a WordCram from a text file, either on the filesystem or the network.
`WordCram`	`fromTextString(java.lang.String... text)` Makes a WordCram from a String of text.
`WordCram`	`fromWebPage(java.lang.String webPageAddress)` Make a WordCram from the text on a web page.
`WordCram`	`fromWords(Word[] words)` Makes a WordCram from your own custom Word array.
`float`	`getProgress()` How far through the words are we? Useful for when drawing to a custom PGraphics.
`Word[]`	`getSkippedWords()` Returns an array of words that could not be placed.
`Word`	`getWordAt(float x, float y)` Get the Word at the given (x,y) coordinates.
`Word[]`	`getWords()` Get the Words that WordCram is drawing.
`boolean`	`hasMore()` If you're drawing the words one-at-a-time using `drawNext()`, this will tell you whether the WordCram has any words left to draw.
`WordCram`	`includeNumbers()` Include numbers from the text in the WordCram.
`WordCram`	`keepCase()` Make the WordCram leave all words cased as they appear in the text.
`WordCram`	`lowerCase()` Make the WordCram change all words to lower-case.
`WordCram`	`maxAttemptsToPlaceWord(int maxAttempts)` How many attempts should be used to place a word.
`WordCram`	`maxNumberOfWordsToDraw(int maxWords)` The maximum number of Words WordCram should try to draw.
`WordCram`	`minShapeSize(int minShapeSize)` The smallest-sized Shape the WordCram should try to draw.
`WordCram`	`sizedByRank(int minSize, int maxSize)` Make the WordCram size words by their rank.
`WordCram`	`sizedByWeight(int minSize, int maxSize)` Make the WordCram size words by their weight, where the "heaviest" word will be sized at `maxSize`.
`WordCram`	`upperCase()` Make the WordCram change all words to upper-case.
`WordCram`	`withAngler(WordAngler angler)` Use the given WordAngler to pick angles for each word.
`WordCram`	`withColor(int color)` Renders all words in the given color.
`WordCram`	`withColorer(WordColorer colorer)` Use the given WordColorer to pick colors for each word.
`WordCram`	`withColors(int... colors)` Render words by randomly choosing from the given colors.
`WordCram`	`withCustomCanvas(processing.core.PGraphics canvas)` Use a custom canvas instead of the applet's default one.
`WordCram`	`withFont(processing.core.PFont font)` Make the WordCram render all words in the given PFont.
`WordCram`	`withFont(java.lang.String fontName)` Make the WordCram render all words in the font that matches the given name, via Processing's createFont.
`WordCram`	`withFonter(WordFonter fonter)` Use the given WordFonter to pick fonts for each word.
`WordCram`	`withFonts(processing.core.PFont... fonts)` This WordCram will render words in one of the given PFonts.
`WordCram`	`withFonts(java.lang.String... fontNames)` This WordCram will get a PFont for each fontName, via createFont, and will render words in one of those PFonts.
`WordCram`	`withNudger(WordNudger nudger)` Use the given WordNudger to pick angles for each word.
`WordCram`	`withPlacer(WordPlacer placer)` Use the given WordPlacer to pick locations for each word.
`WordCram`	`withSizer(WordSizer sizer)` Use the given WordSizer to pick fonts for each word.
`WordCram`	`withStopWords(java.lang.String extraStopWords)` Tells WordCram which words to ignore when it counts up the words in your text.
`WordCram`	`withWordPadding(int padding)` Add padding around each word, so they stand out from each other more.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - WAS_OVER_MAX_NUMBER_OF_WORDS
```
public static final int WAS_OVER_MAX_NUMBER_OF_WORDS
```
    Skip Reason: the Word was skipped because maxNumberOfWordsToDraw(int) was set to some value, and the Word came in over that limit. It's really about the Word's rank, its position in the list once the words are sorted by weight: if its rank is greater than the value passed to maxNumberOfWordsToDraw(), then it'll be skipped, and this will be the reason code.
    
    See Also:
    Constant Field Values
  - SHAPE_WAS_TOO_SMALL
```
public static final int SHAPE_WAS_TOO_SMALL
```
    Skip Reason: the Word's shape was too small. WordCram will only render words so small, for performance reasons. You can set the minimum Word shape size via minShapeSize(int).
    
    See Also:
    Constant Field Values
  - NO_SPACE
```
public static final int NO_SPACE
```
    Skip Reason: WordCram tried placing the Word, but it couldn't find a clear spot. The WordNudger nudged it around a bunch (according to maxAttemptsToPlaceWord(int), if it was set), but there was just no room.
    
    See Also:
    Constant Field Values
- Constructor Detail
  - WordCram
```
public WordCram(processing.core.PApplet parent)
```
    Make a new WordCram.
    It's the starting point of the fluent API for building WordCrams.
    
    Parameters:
    parent - Your Processing sketch. Pass it as this.
- Method Detail
  - withStopWords
```
public WordCram withStopWords(java.lang.String extraStopWords)
```
    Tells WordCram which words to ignore when it counts up the words in your text. These words won't show up in the image.
    Stop-words are always case-insensitive: if your source text contains "The plane, the plane!", using "the" for a stop-word is enough to block both "the" and "The".
    It doesn't matter whether this is called before or after the "for{text}" methods.
    Note: Stop-words have no effect if you're passing in your own custom Word array, since WordCram won't do any text analysis on it (other than sorting the words and scaling their weights).
    
    Parameters:
    extraStopWords - a space-delimited String of words to ignore when counting the words in your text.
    
    Returns:
    The WordCram, for further setup or drawing.
  - excludeNumbers
```
public WordCram excludeNumbers()
```
    Exclude numbers from the text in the WordCram. They're excluded by default.
    Words that are all numbers, like 1, 3.14159, 42, or 1492, will be excluded. Words that have some letters and some numbers like 1A, U2, or funnyguy194 will be included.
    
    Returns:
    The WordCram, for further setup or drawing.
    See Also:
    includeNumbers()
  - includeNumbers
```
public WordCram includeNumbers()
```
    Include numbers from the text in the WordCram. They're excluded by default.
    
    Returns:
    The WordCram, for further setup or drawing.
    See Also:
    excludeNumbers()
  - lowerCase
```
public WordCram lowerCase()
```
    Make the WordCram change all words to lower-case. Stop-words are unaffected; they're always case-insensitive. The default is to keep words as they appear in the text.
    
    Returns:
    The WordCram, for further setup or drawing.
  - upperCase
```
public WordCram upperCase()
```
    Make the WordCram change all words to upper-case. Stop-words are unaffected; they're always case-insensitive. The default is to keep words as they appear in the text.
    
    Returns:
    The WordCram, for further setup or drawing.
  - keepCase
```
public WordCram keepCase()
```
    Make the WordCram leave all words cased as they appear in the text. Stop-words are unaffected; they're always case-insensitive. This is the default.
    
    Returns:
    The WordCram, for further setup or drawing.
  - fromWebPage
```
public WordCram fromWebPage(java.lang.String webPageAddress)
```
    Make a WordCram from the text on a web page. Just before the WordCram is drawn, it'll load the web page's HTML, scrape out the text, and count and sort the words.
    
    Parameters:
    webPageAddress - the URL of the web page to load
    
    Returns:
    The WordCram, for further setup or drawing.
  - fromHtmlFile
```
public WordCram fromHtmlFile(java.lang.String htmlFilePath)
```
    Make a WordCram from the text in a HTML file. Just before the WordCram is drawn, it'll load the file's HTML, scrape out the text, and count and sort the words.
    
    Parameters:
    htmlFilePath - the path of the html file to load
    
    Returns:
    The WordCram, for further setup or drawing.
  - fromHtmlString
```
public WordCram fromHtmlString(java.lang.String... html)
```
    Makes a WordCram from a String of HTML. Just before the WordCram is drawn, it'll scrape out the text from the HTML, and count and sort the words. It takes one String, or any number of Strings, or an array of Strings, so you can easily use it with loadStrings().
    
    Parameters:
    html - the String(s) of HTML
    
    Returns:
    The WordCram, for further setup or drawing.
  - fromTextFile
```
public WordCram fromTextFile(java.lang.String textFilePathOrUrl)
```
    Makes a WordCram from a text file, either on the filesystem or the network. Just before the WordCram is drawn, it'll load the file, and count and sort its words.
    
    Parameters:
    textFilePathOrUrl - the path of the text file
    
    Returns:
    The WordCram, for further setup or drawing.
  - fromTextString
```
public WordCram fromTextString(java.lang.String... text)
```
    Makes a WordCram from a String of text. It takes one String, or any number of Strings, or an array of Strings, so you can easily use it with loadStrings().
    
    Parameters:
    text - the String of text to get the words from
    
    Returns:
    The WordCram, for further setup or drawing.
  - fromText
```
public WordCram fromText(TextSource textSource)
```
    Makes a WordCram from any TextSource.
    It only caches the TextSource - it won't load the text from it until drawAll() or drawNext() is called.
    
    Parameters:
    textSource - the TextSource to get the text from.
    
    Returns:
    The WordCram, for further setup or drawing.
  - fromWords
```
public WordCram fromWords(Word[] words)
```
    Makes a WordCram from your own custom Word array. The Words can be ordered and weighted arbitrarily - WordCram will sort them by weight, and then divide their weights by the weight of the heaviest Word, so the heaviest Word will end up with a weight of 1.0.
    Note: WordCram won't do any text analysis on the words; stop-words will have no effect, etc. These words are supposed to be ready to go.
    
    Returns:
    The WordCram, for further setup or drawing.
  - withFonts
```
public WordCram withFonts(java.lang.String... fontNames)
```
    This WordCram will get a PFont for each fontName, via createFont, and will render words in one of those PFonts.
    
    Returns:
    The WordCram, for further setup or drawing.
  - withFont
```
public WordCram withFont(java.lang.String fontName)
```
    Make the WordCram render all words in the font that matches the given name, via Processing's createFont.
    
    Parameters:
    fontName - the font name to pass to createFont.
    
    Returns:
    The WordCram, for further setup or drawing.
  - withFonts
```
public WordCram withFonts(processing.core.PFont... fonts)
```
    This WordCram will render words in one of the given PFonts.
    
    Returns:
    The WordCram, for further setup or drawing.
  - withFont
```
public WordCram withFont(processing.core.PFont font)
```
    Make the WordCram render all words in the given PFont.
    
    Parameters:
    font - the PFont to render the words in.
    
    Returns:
    The WordCram, for further setup or drawing.
  - withFonter
```
public WordCram withFonter(WordFonter fonter)
```
    Use the given WordFonter to pick fonts for each word. You can make your own, or use a pre-fab one from Fonters.
    
    Parameters:
    fonter - the WordFonter to use.
    
    Returns:
    The WordCram, for further setup or drawing.
    See Also:
    WordFonter, Fonters
  - sizedByWeight
```
public WordCram sizedByWeight(int minSize,
                     int maxSize)
```
    Make the WordCram size words by their weight, where the "heaviest" word will be sized at maxSize.
    Specifically, it makes the WordCram use Sizers.byWeight(int, int).
    
    Parameters:
    minSize - the size to draw a Word of weight 0
    maxSize - the size to draw a Word of weight 1
    
    Returns:
    The WordCram, for further setup or drawing.
  - sizedByRank
```
public WordCram sizedByRank(int minSize,
                   int maxSize)
```
    Make the WordCram size words by their rank. The first word will be sized at maxSize.
    Specifically, it makes the WordCram use Sizers.byRank(int, int).
    
    Parameters:
    minSize - the size to draw the last Word
    maxSize - the size to draw the first Word
    
    Returns:
    The WordCram, for further setup or drawing.
  - withSizer
```
public WordCram withSizer(WordSizer sizer)
```
    Use the given WordSizer to pick fonts for each word. You can make your own, or use a pre-fab one from Sizers.
    
    Parameters:
    sizer - the WordSizer to use.
    
    Returns:
    The WordCram, for further setup or drawing.
    See Also:
    WordSizer, Sizers
  - withColors
```
public WordCram withColors(int... colors)
```
    Render words by randomly choosing from the given colors. Uses Colorers.pickFrom(int...).
    Note: if you want all your words to be, say, red, don't do this:
```
 ...withColors(255, 0, 0)...  // Not what you want!
 
```
    You'll just see a blank WordCram. Since Processing stores colors as integers, WordCram will see each integer as a different color, and it'll color about 1/3 of your words with the color represented by the integer 255, and the other 2/3 with the color represented by the integer 0. The punchline is, Processing stores opacity (or alpha) in the highest bits (the ones used for storing really big numbers, from 2²⁴ to 2³²), so your colors 0 and 255 have, effectively, 0 opacity -- they're completely transparent. Oops.
    Use this instead, and you'll get what you're after:
```
 ...withColors(color(255, 0, 0))...  // Much better!
 
```
    Parameters:
    colors - the colors to randomly choose from.
    
    Returns:
    The WordCram, for further setup or drawing.
  - withColor
```
public WordCram withColor(int color)
```
    Renders all words in the given color.
    
    Parameters:
    color - the color for each word.
    
    Returns:
    The WordCram, for further setup or drawing.
    See Also:
    withColors(int...)
  - withColorer
```
public WordCram withColorer(WordColorer colorer)
```
    Use the given WordColorer to pick colors for each word. You can make your own, or use a pre-fab one from Colorers.
    
    Parameters:
    colorer - the WordColorer to use.
    
    Returns:
    The WordCram, for further setup or drawing.
    See Also:
    WordColorer, Colorers
  - angledAt
```
public WordCram angledAt(float... anglesInRadians)
```
    Make the WordCram rotate each word at one of the given angles.
    
    Parameters:
    anglesInRadians - The list of possible rotation angles, in radians
    
    Returns:
    The WordCram, for further setup or drawing.
  - angledBetween
```
public WordCram angledBetween(float minAngleInRadians,
                     float maxAngleInRadians)
```
    Make the WordCram rotate words randomly, between the min and max angles.
    
    Parameters:
    minAngleInRadians - The minimum rotation angle, in radians
    maxAngleInRadians - The maximum rotation angle, in radians
    
    Returns:
    The WordCram, for further setup or drawing.
  - withAngler
```
public WordCram withAngler(WordAngler angler)
```
    Use the given WordAngler to pick angles for each word. You can make your own, or use a pre-fab one from Anglers.
    
    Parameters:
    angler - the WordAngler to use.
    
    Returns:
    The WordCram, for further setup or drawing.
    See Also:
    WordAngler, Anglers
  - withPlacer
```
public WordCram withPlacer(WordPlacer placer)
```
    Use the given WordPlacer to pick locations for each word. You can make your own, or use a pre-fab one from Placers.
    
    Parameters:
    placer - the WordPlacer to use.
    
    Returns:
    The WordCram, for further setup or drawing.
    See Also:
    WordPlacer, Placers, PlottingWordPlacer
  - withNudger
```
public WordCram withNudger(WordNudger nudger)
```
    Use the given WordNudger to pick angles for each word. You can make your own, or use a pre-fab one.
    
    Parameters:
    nudger - the WordNudger to use.
    
    Returns:
    The WordCram, for further setup or drawing.
    See Also:
    WordNudger, SpiralWordNudger, RandomWordNudger, PlottingWordNudger
  - maxAttemptsToPlaceWord
```
public WordCram maxAttemptsToPlaceWord(int maxAttempts)
```
    How many attempts should be used to place a word. Higher values ensure that more words get placed, but will make algorithm slower.
    
    Parameters:
    maxAttempts -
    
    Returns:
    The WordCram, for further setup or drawing.
  - maxNumberOfWordsToDraw
```
public WordCram maxNumberOfWordsToDraw(int maxWords)
```
    The maximum number of Words WordCram should try to draw. This might be useful if you have a whole bunch of words, and need an artificial way to cut down the list (for speed). By default, it's unlimited.
    
    Parameters:
    maxWords - can be any value from 0 to Integer.MAX_VALUE. Values < 0 are treated as unlimited.
    
    Returns:
    The WordCram, for further setup or drawing.
  - minShapeSize
```
public WordCram minShapeSize(int minShapeSize)
```
    The smallest-sized Shape the WordCram should try to draw. By default, it's 7.
    
    Parameters:
    minShapeSize - the size of the smallest Shape.
    
    Returns:
    The WordCram, for further setup or drawing.
  - withCustomCanvas
```
public WordCram withCustomCanvas(processing.core.PGraphics canvas)
```
    Use a custom canvas instead of the applet's default one. This may be needed if rendering in background or in other dimensions than the applet size is needed.
    
    Parameters:
    canvas - the canvas to draw to
    
    Returns:
    The WordCram, for further setup or drawing.
  - withWordPadding
```
public WordCram withWordPadding(int padding)
```
    Add padding around each word, so they stand out from each other more. If you call this multiple times, the last value will be used. WordCram uses a tree of java.awt.Rectangle objects to detect whether two words overlap. What this method actually does is call Rectangle.grow(padding) on the leaves of that tree.
    
    Parameters:
    padding - The number of pixels to grow each rectangle by. Defaults to zero.
    
    Returns:
    The WordCram, for further setup or drawing.
  - hasMore
```
public boolean hasMore()
```
    If you're drawing the words one-at-a-time using drawNext(), this will tell you whether the WordCram has any words left to draw.
    
    Returns:
    true if the WordCram has any words left to draw; false otherwise.
    See Also:
    drawNext()
  - drawNext
```
public void drawNext()
```
    If the WordCram has any more words to draw, draw the next one.
    
    See Also:
    hasMore(), drawAll()
  - drawAll
```
public void drawAll()
```
    Just like it sounds: draw all the words. Once the WordCram has everything set, call this and wait just a bit.
    
    See Also:
    drawNext()
  - getWords
```
public Word[] getWords()
```
    Get the Words that WordCram is drawing. This can be useful if you want to inspect exactly how the words were weighted, or see how they were colored, fonted, sized, angled, or placed, or why they were skipped.
  - getWordAt
```
public Word getWordAt(float x,
             float y)
```
    Get the Word at the given (x,y) coordinates.
    This can be called while the WordCram is rendering, or after it's done. If a Word is too small to render, or hasn't been placed yet, it will never be returned by this method.
    
    Parameters:
    x - the X coordinate
    y - the Y coordinate
    
    Returns:
    the Word that covers those coordinates, or null if there isn't one
  - getSkippedWords
```
public Word[] getSkippedWords()
```
    Returns an array of words that could not be placed.
    
    Returns:
    An array of the skipped words
  - getProgress
```
public float getProgress()
```
    How far through the words are we? Useful for when drawing to a custom PGraphics.
    
    Returns:
    The current point of progress through the list, as a float between 0 and 1.

Class WordCram

Step One: Weight Your Words

Let WordCram Weight Your Words

Weight Your Own Words

Step Two: Style Your Words

How big should it be?

How should it be angled?

What font should it be in?

How should it be colored?

Where on the image should it go?

If it doesn't fit at first, how should I nudge it?

Step Three: Draw Your WordCram

Step Three-and-a-Half: How Did It Go?

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

WAS_OVER_MAX_NUMBER_OF_WORDS

SHAPE_WAS_TOO_SMALL

NO_SPACE

Constructor Detail

WordCram

Method Detail

withStopWords

excludeNumbers

includeNumbers

lowerCase

upperCase

keepCase

fromWebPage

fromHtmlFile

fromHtmlString

fromTextFile

fromTextString

fromText

fromWords

withFonts

withFont

withFonts

withFont

withFonter

sizedByWeight

sizedByRank

withSizer

withColors

withColor

withColorer

angledAt

angledBetween

withAngler

withPlacer

withNudger

maxAttemptsToPlaceWord

maxNumberOfWordsToDraw

minShapeSize

withCustomCanvas

withWordPadding

hasMore

drawNext

drawAll

getWords

getWordAt

getSkippedWords

getProgress