001package squidpony.panel;
002
003import squidpony.IColorCenter;
004import squidpony.annotation.Beta;
005
006/**
007 * The abstraction of {@code SquidPanel}s, to abstract from the UI
008 * implementation (i.e. whether it's awt or libgdx doesn't matter here).
009 * 
010 * @author smelC - Introduction of this interface, but methods were in
011 *         SquidPanel already.
012 * 
013 * @param <T>
014 *            The type of colors
015 * 
016 * @see ICombinedPanel The combination of two panels, one for the background,
017 *      one for the foreground; a frequent use case in roguelikes.
018 */
019@Beta
020public interface ISquidPanel<T> {
021
022        /**
023         * Puts the character {@code c} at {@code (x, y)}.
024         * 
025         * @param x
026         * @param y
027         * @param c
028         */
029        void put(int x, int y, char c);
030
031        /**
032         * Puts {@code color} at {@code (x, y)} (in the cell's entirety, i.e. in the
033         * background).
034         * 
035         * @param x
036         * @param y
037         * @param color
038         */
039        void put(int x, int y, T color);
040
041        /**
042         * Puts the given string horizontally with the first character at the given
043         * offset.
044         *
045         * Does not word wrap. Characters that are not renderable (due to being at
046         * negative offsets or offsets greater than the grid size) will not be shown
047         * but will not cause any malfunctions.
048         *
049         * @param xOffset
050         *            the x coordinate of the first character
051         * @param yOffset
052         *            the y coordinate of the first character
053         * @param string
054         *            the characters to be displayed
055         * @param foreground
056         *            the color to draw the characters
057         */
058        void put(int xOffset, int yOffset, String string, T foreground);
059
060        /**
061         * Puts the given string horizontally with the first character at the given
062         * offset, using the colors that {@code cs} provides.
063         *
064         * Does not word wrap. Characters that are not renderable (due to being at
065         * negative offsets or offsets greater than the grid size) will not be shown
066         * but will not cause any malfunctions.
067         *
068         * @param xOffset
069         *            the x coordinate of the first character
070         * @param yOffset
071         *            the y coordinate of the first character
072         * @param cs
073         *            The string to display, with its colors.
074         */
075        void put(int xOffset, int yOffset, IColoredString<? extends T> cs);
076
077        /**
078         * Puts the character {@code c} at {@code (x, y)} with some {@code color}.
079         * 
080         * @param x
081         * @param y
082         * @param c
083         * @param color
084         */
085        void put(int x, int y, char c, T color);
086
087        /**
088         * @param foregrounds
089         *            Can be {@code null}, indicating that only colors must be put.
090         * @param colors
091         */
092        void put(/* @Nullable */ char[][] foregrounds, T[][] colors);
093
094        /**
095         * Removes the contents of this cell, leaving a transparent space.
096         *
097         * @param x
098         * @param y
099         */
100        void clear(int x, int y);
101
102        /**
103         * @return The number of cells that this panel spans, horizontally.
104         */
105        int gridWidth();
106
107        /**
108         * @return The number of cells that this panel spans, vertically.
109         */
110        int gridHeight();
111
112        /**
113         * @return The width of a cell, in number of pixels.
114         */
115        int cellWidth();
116
117        /**
118         * @return The height of a cell, in number of pixels.
119         */
120        int cellHeight();
121
122        /**
123         * @return Returns true if there are animations running when this method is
124         *         called.
125         */
126        boolean hasActiveAnimations();
127
128        /**
129         * Sets the default foreground color.
130         * 
131         * @param color
132         */
133        void setDefaultForeground(T color);
134
135        /**
136         * @return The default foreground color (if none was set with
137         *         {@link #setDefaultForeground(Object)}), or the last color set
138         *         with {@link #setDefaultForeground(Object)}. Cannot be
139         *         {@code null}.
140         */
141        T getDefaultForegroundColor();
142
143        /**
144         * Method to change the backing {@link IColorCenter}.
145         * 
146         * @param icc
147         * @return {@code this}
148         */
149        ISquidPanel<T> setColorCenter(IColorCenter<T> icc);
150
151        /**
152         * @return The panel doing the real job, i.e. an instance of
153         *         {@code SquidPanel}. The type of colors is unspecified, as some
154         *         clients have forwarding instances of this class that hides that
155         *         the type of color of the backer differs from the type of color in
156         *         {@code this}.
157         * 
158         *         <p>
159         *         Can be {@code this} itself.
160         *         </p>
161         */
162        ISquidPanel<?> getBacker();
163
164}