001package squidpony.squidgrid.gui.gdx;
002
003import com.badlogic.gdx.graphics.Color;
004import squidpony.panel.IColoredString;
005
006/**
007 * Created by Tommy Ettinger on 8/5/2017.
008 */
009public interface IPackedColorPanel {
010    /**
011     * Places a full cell of color at the given x,y position; this may be used as a background or foreground, depending
012     * on the implementation. The color is given as a packed float, the kind produced by {@link Color#toFloatBits()}.
013     * If the implementation performs color filtering on Color objects, it generally won't on packed float colors.
014     * @param x x position of the cell
015     * @param y y position of the cell
016     * @param color color for the full cell as a packed float, as made by {@link Color#toFloatBits()}
017     */
018    void put(int x, int y, float color);
019
020    /**
021     * Using the existing color at the position x,y, this performs color blending from that existing color to the given
022     * color (as a float), using the mixBy parameter to determine how much of the color parameter to use (1f will set
023     * the color in this to the parameter, while 0f for mixBy will ignore the color parameter entirely).
024     * @param x the x component of the position in this panel to draw the starting color from
025     * @param y the y component of the position in this panel to draw the starting color from
026     * @param color the new color to mix with the starting color; a packed float, as made by {@link Color#toFloatBits()}
027     * @param mixBy the amount by which the new color will affect the old one, between 0 (no effect) and 1 (overwrite)
028     */
029    void blend(int x, int y, float color, float mixBy);
030
031    /**
032     * Places a char in the given color at the given x,y position; if the implementation has a separate background from
033     * the foreground characters, this will not affect it. The color is given as a packed float, the kind produced by
034     * {@link Color#toFloatBits()}. If the implementation performs color filtering on Color objects, it generally won't
035     * on packed float colors.
036     * @param x x position of the char
037     * @param y y position of the char
038     * @param c the char to put at the given cell
039     * @param encodedColor the color for the char as a packed float, as made by {@link Color#toFloatBits()}
040     */
041    void put(int x, int y, char c, float encodedColor);
042
043    /**
044     * Puts the character {@code c} at {@code (x, y)}.
045     *
046     * @param x
047     * @param y
048     * @param c
049     */
050    void put(int x, int y, char c);
051
052    /**
053     * Puts {@code color} at {@code (x, y)} (in the cell's entirety, i.e. in the
054     * background).
055     *
056     * @param x
057     * @param y
058     * @param color
059     */
060    void put(int x, int y, Color color);
061
062    /**
063     * Puts the given string horizontally with the first character at the given
064     * offset.
065     *
066     * Does not word wrap. Characters that are not renderable (due to being at
067     * negative offsets or offsets greater than the grid size) will not be shown
068     * but will not cause any malfunctions.
069     *
070     * @param xOffset
071     *            the x coordinate of the first character
072     * @param yOffset
073     *            the y coordinate of the first character
074     * @param string
075     *            the characters to be displayed
076     * @param foreground
077     *            the color to draw the characters
078     */
079    void put(int xOffset, int yOffset, String string, Color foreground);
080
081    /**
082     * Puts the given string horizontally with the first character at the given
083     * offset, using the colors that {@code cs} provides.
084     *
085     * Does not word wrap. Characters that are not renderable (due to being at
086     * negative offsets or offsets greater than the grid size) will not be shown
087     * but will not cause any malfunctions.
088     *
089     * @param xOffset
090     *            the x coordinate of the first character
091     * @param yOffset
092     *            the y coordinate of the first character
093     * @param cs
094     *            The string to display, with its colors.
095     */
096    void put(int xOffset, int yOffset, IColoredString<? extends Color> cs);
097
098    /**
099     * Puts the character {@code c} at {@code (x, y)} with some {@code color}.
100     *
101     * @param x
102     * @param y
103     * @param c
104     * @param color
105     */
106    void put(int x, int y, char c, Color color);
107
108    /**
109     * @param foregrounds
110     *            Can be {@code null}, indicating that only colors must be put.
111     * @param colors
112     */
113    void put(/* @Nullable */ char[][] foregrounds, Color[][] colors);
114
115    /**
116     * Removes the contents of this cell, leaving a transparent space.
117     *
118     * @param x
119     * @param y
120     */
121    void clear(int x, int y);
122
123    /**
124     * @return The number of cells that this panel spans, horizontally.
125     */
126    int gridWidth();
127
128    /**
129     * @return The number of cells that this panel spans, vertically.
130     */
131    int gridHeight();
132
133    /**
134     * @return The width of a cell, in number of pixels.
135     */
136    int cellWidth();
137
138    /**
139     * @return The height of a cell, in number of pixels.
140     */
141    int cellHeight();
142
143    /**
144     * @return Returns true if there are animations running when this method is
145     *         called.
146     */
147    boolean hasActiveAnimations();
148
149    /**
150     * Sets the default foreground color.
151     *
152     * @param color
153     */
154    void setDefaultForeground(Color color);
155
156    /**
157     * @return The default foreground color (if none was set with
158     *         {@link #setDefaultForeground(Color)}), or the last color set
159     *         with {@link #setDefaultForeground(Color)}. Cannot be
160     *         {@code null}.
161     */
162    Color getDefaultForegroundColor();
163
164}