squidpony.panel.IMarkup Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of squidlib-util Show documentation
Show all versions of squidlib-util Show documentation
SquidLib platform-independent logic and utility code. Please refer to
https://github.com/SquidPony/SquidLib .
package squidpony.panel;
/**
* An interface that lets non-display code request some special rendering for a {@code T} value, and an implementation
* can handle this appropriately in display code. Much of the time, IMarkup will not be directly used in games, and it
* may have much of its value in library code that can use it to declare that some value should be shown in larger text,
* or in a certain color, without specifying the exact details of what shade of what color or precisely how much larger
* the text should be. However, there may be good uses for highly-specific custom implementations of IMarkup for types
* present only in one game, where {@code T} may be {@code Creature} or some other class specific to a game, and the
* IMarkup can be used to get a special String to describe or display that Creature with any color/size markup or even
* a String that changes over time. The {@link #getMarkup(Object)} method yields the appropriate text or markup to
* describe its parameter, and the {@link #closeMarkup()} method yields text that ends any block of markup that is
* ongoing. For the example of an IMarkup for colors, getMarkup would be given a color parameter and would color any
* text in that color or a variant on it until the markup is closed with closeMarkup, or possibly until the color is
* specified again via getMarkup. For the example of IMarkup for Creatures, getMarkup would produce a String that
* describes the Creature it is given as a parameter (if it uses colors/sizes as well, it should close itself to be
* self-contained), and closeMarkup would produce the empty String.
* Created by Tommy Ettinger on 1/23/2016.
*/
public interface IMarkup {
/**
* Implementations should use this method to get a String that describes the given value, or begins some section of
* markup that uses a quality specified by value, such as a color or text size.
* @param value an object of type T that can be described by this IMarkup implementation
* @return a String either describing the value or starting a section of markup using the value.
*/
String getMarkup(T value);
/**
* Implementations should use this method to get a String that ends any section of markup currently ongoing.
* This may be the empty String in many cases.
* @return the requisite String to end any ongoing sections of markup
*/
String closeMarkup();
// escape() is currently commented out because I don't know if it is needed.
/*
* If the Strings used as markup may occur in normal text, you can call this on the text before applying markup to
* escape the not-actually-markup Strings in the text. If your variety of markup doesn't have a concept of escaping,
* this can return initialText as-is.
* @param initialText the text to process, before applying markup
* @return a String made from initialText, with any pre-existing Strings that could be read as markup escaped
* /
String escape(String initialText);
*/
/**
* Probably not that useful on its own, but may be good as an example.
* @see squidpony.panel.IMarkup IMarkup has more complete documentation on how it should be used
*/
class StringMarkup implements IMarkup
{
@Override
public String getMarkup(String value) {
return "[" + value + "]";
}
@Override
public String closeMarkup() {
return "[]";
}
/*
@Override
public String escape(String initialText)
{
return initialText.replace("[", "[[");
}
*/
}
}