1 /* 2 * Copyright (C) 2010 The Android Open Source Project 3 * 4 * Licensed under the Eclipse Public License, Version 1.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.eclipse.org/org/documents/epl-v10.php 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.android.ide.common.api; 18 19 import java.util.List; 20 21 /** 22 * Represents a graphical context that rules can use to draw on the canvas. 23 * <p/> 24 * The wrapper GC is only valid during the context of a paint operation. 25 * This means {@link IViewRule}s should not cache this object and call it at 26 * just about any time, it is only valid during a call that actually receives 27 * the GC wrapper. 28 * <p> 29 * <b>NOTE: This is not a public or final API; if you rely on this be prepared 30 * to adjust your code for the next tools release.</b> 31 * </p> 32 */ 33 public interface IGraphics { 34 35 /** 36 * Draws a line between 2 points, using the current foreground color and 37 * alpha. 38 */ drawLine(int x1, int y1, int x2, int y2)39 void drawLine(int x1, int y1, int x2, int y2); 40 41 /** 42 * Draws a line between 2 points, using the current foreground color and 43 * alpha. 44 */ drawLine(Point p1, Point p2)45 void drawLine(Point p1, Point p2); 46 47 /** 48 * Draws an arrow from (x1, y1) to (x2, y2). 49 * 50 * @param x1 The x coordinate of the beginning of the arrow 51 * @param y1 The y coordinate of the beginning of the arrow 52 * @param x2 The x coordinate of the end (point) of the arrow 53 * @param y2 The y coordinate of the end (point) of the arrow 54 * @param size The size of the arrowhead 55 */ drawArrow(int x1, int y1, int x2, int y2, int size)56 void drawArrow(int x1, int y1, int x2, int y2, int size); 57 58 /** 59 * Draws a dot at the given position. 60 * 61 * @param x The x coordinate of the dot 62 * @param y The y coordinate of the dot 63 */ drawPoint(int x, int y)64 void drawPoint(int x, int y); 65 66 /** 67 * Draws a rectangle outline between 2 points, using the current foreground 68 * color and alpha. 69 */ drawRect(int x1, int y1, int x2, int y2)70 void drawRect(int x1, int y1, int x2, int y2); 71 72 /** 73 * Draws a rectangle outline between 2 points, using the current foreground 74 * color and alpha. 75 */ drawRect(Point p1, Point p2)76 void drawRect(Point p1, Point p2); 77 78 /** 79 * Draws a rectangle outline between 2 points, using the current foreground 80 * color and alpha. 81 */ drawRect(Rect r)82 void drawRect(Rect r); 83 84 /** 85 * Fills a rectangle outline between 2 points, using the current background 86 * color and alpha. 87 */ fillRect(int x1, int y1, int x2, int y2)88 void fillRect(int x1, int y1, int x2, int y2); 89 90 /** 91 * Fills a rectangle outline between 2 points, using the current background 92 * color and alpha. 93 */ fillRect(Point p1, Point p2)94 void fillRect(Point p1, Point p2); 95 96 /** 97 * Fills a rectangle outline between 2 points, using the current background 98 * color and alpha. 99 */ fillRect(Rect r)100 void fillRect(Rect r); 101 102 /** 103 * Draws the given string, using the current foreground color. No tab 104 * expansion or carriage return processing will be performed. 105 * 106 * @param string the string to be drawn. 107 * @param x the x coordinate of the top left corner of the text. 108 * @param y the y coordinate of the top left corner of the text. 109 */ drawString(String string, int x, int y)110 void drawString(String string, int x, int y); 111 112 /** 113 * Draws the given string, using the current foreground color. No tab 114 * expansion or carriage return processing will be performed. 115 * 116 * @param string the string to be drawn. 117 * @param topLeft the top left corner of the text. 118 */ drawString(String string, Point topLeft)119 void drawString(String string, Point topLeft); 120 121 /** 122 * Draw the given strings, using the current stroke color and alpha for the 123 * text, and the current fill color and alpha for a rectangle behind the 124 * bounding box fitting all the lines of text. Each subsequent string is 125 * drawn on consecutive lines below the previous string. 126 * 127 * @param x The left edge to start each string at 128 * @param y The top position of the first string; subsequent strings are 129 * painted on lines below 130 * @param strings An array of labels to be displayed (should not be null). 131 * The actual String used is the {@link Object#toString()} value 132 * of each list item. 133 */ drawBoxedStrings(int x, int y, List<?> strings)134 void drawBoxedStrings(int x, int y, List<?> strings); 135 136 /** 137 * Set up the graphics context to use the given style for subsequent drawing 138 * operations. 139 * 140 * @param style The drawing style to be used. May not be null. 141 */ useStyle(DrawingStyle style)142 void useStyle(DrawingStyle style); 143 144 /** 145 * Registers a color using 0x00rrggbb where each component is 0..0xFF. 146 * <p/> 147 * Transparency is handled separately using {@link #setAlpha(int)}. 148 * <p/> 149 * If the same color is registered twice, the same object will be returned. 150 * <p/> 151 * NOTE: It's preferable to use {@link #useStyle(DrawingStyle)} if possible 152 * to ensure that your colors work properly across multiple current and 153 * future themes. 154 */ registerColor(int rgb)155 IColor registerColor(int rgb); 156 157 /** 158 * Returns the height, in pixels, of the default font. 159 */ getFontHeight()160 int getFontHeight(); 161 162 /** 163 * Returns the current foreground color. 164 * The foreground color is used for drawing operations including when text is drawn. 165 */ getForeground()166 IColor getForeground(); 167 168 /** 169 * Sets the foreground color. The foreground color is used for drawing 170 * operations including when text is drawn. 171 */ setForeground(IColor color)172 void setForeground(IColor color); 173 174 /** 175 * Returns the current background color. The background color is used for 176 * fill operations. 177 */ getBackground()178 IColor getBackground(); 179 180 /** 181 * Sets the background color. The background color is used for fill 182 * operations. 183 */ setBackground(IColor color)184 void setBackground(IColor color); 185 186 /** 187 * Returns the current alpha value (varies between 0 for transparent and 255 188 * for opaque). 189 * 190 * @return The current alpha value in use 191 */ getAlpha()192 int getAlpha(); 193 194 /** 195 * Sets the receiver's alpha value which must be 196 * between 0 (transparent) and 255 (opaque). 197 * <p> 198 * This operation requires the operating system's advanced 199 * graphics subsystem which may not be available on some 200 * platforms. 201 * <p> 202 * TODO: Consider removing this method; it will usually be ignored because 203 * most graphics operations apply the alpha from the current drawing style 204 */ setAlpha(int alpha)205 void setAlpha(int alpha); 206 207 /** 208 * A line style for {@link IGraphics#setLineStyle(LineStyle)}. 209 */ 210 enum LineStyle { 211 /** Style for solid lines. */ 212 LINE_SOLID, 213 /** Style for dashed lines. */ 214 LINE_DASH, 215 /** Style for dotted lines. */ 216 LINE_DOT, 217 /** Style for alternating dash-dot lines. */ 218 LINE_DASHDOT, 219 /** Style for dash-dot-dot lines. */ 220 LINE_DASHDOTDOT 221 } 222 223 /** 224 * Sets the current line style. 225 */ setLineStyle(LineStyle style)226 void setLineStyle(LineStyle style); 227 228 /** 229 * Sets the width that will be used when drawing lines. 230 * The operation is ignored if <var>width</var> is less than 1. 231 */ setLineWidth(int width)232 void setLineWidth(int width); 233 } 234