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