001 /*
002 * Copyright 2007,2008,2009 John C. Gunther, except that most of this
003 * GChartCanvasLite interface was extracted from GWTCanvas, a part of the
004 * GWT incubator project, which is Copyright Google, Inc. and also
005 * licenced under Apache 2.0.
006 *
007 * Licensed under the Apache License, Version 2.0 (the
008 * "License"); you may not use this file except in compliance
009 * with the License. You may obtain a copy of the License at:
010 *
011 * http://www.apache.org/licenses/LICENSE-2.0
012 *
013 * Unless required by applicable law or agreed to in writing,
014 * software distributed under the License is distributed on an
015 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
016 * either express or implied. See the License for the specific
017 * language governing permissions and limitations under the
018 * License.
019 */
020 package com.googlecode.gchart.client;
021 /**
022 * Defines the features of a canvas (vector graphics) widget
023 * that (once you teach GChart how to create such widgets via
024 * the <tt>setCanvasFactory</tt> method) GChart can exploit to
025 * render your charts more quickly and with higher resolution.
026 *
027 * <p>
028 *
029 * Names, method signatures, and javadoc comments for this
030 * interface are mostly copied from, and a proper subset of,
031 * the GWT incubator's <a
032 * href="http://code.google.com/p/google-web-toolkit-incubator/wiki/GWTCanvas">
033 * GWTCanvas widget</a>. Specifically, for simplicity, features
034 * of <tt>GWTCanvas</tt> that GChart can't exploit, such as gradients and
035 * transformations, have been omitted, and only ordinary CSS
036 * and RGBA color strings (not the special <tt>GWTCanvas
037 * Color</tt> type) are supported.
038 * <p>
039 *
040 * The original <tt>GWTCanvas</tt> code is copyright Google, Inc. under
041 * the terms of the Apache 2.0 license.<p>
042 *
043 *
044 * <i>Tip:</i> To easily bolt-on <tt>GWTCanvas</tt> to render your
045 * charts more quickly and with higher resolution, just add the
046 * <tt>gwt-incubator.jar</tt> to your build path, and copy the
047 * boilerplate code in the <tt>setCanvasFactory</tt> method's
048 * javadocs into the module that contains your application's
049 * EntryPoint class. If you decide instead to use a different GWT
050 * cross-browser vector graphics widget, you can still use that
051 * boilerplate as a starting point for your own, custom, interfacing
052 * code.
053 * <p>
054 *
055 * <small> GChart requires that the background color of the
056 * canvas element as a whole be transparent (no background
057 * color). This is needed because, to facilitate single-curve
058 * updating, GChart stitches together the canvas based
059 * rendering of a chart from a series of smaller, overlaid,
060 * canvas widgets. Since transparent backgrounds are the
061 * default for <tt>GWTCanvas</tt>, and likely for other GWT vector
062 * graphics widgets, you are not expected to have to do
063 * anything special to meet this requirement. </small>
064 *
065 *
066 * @see GChartCanvasFactory GChartCanvasFactory
067 * @see GChart#setCanvasFactory setCanvasFactory
068 * @see GChart.Symbol#setFillSpacing setFillSpacing
069 * @see GChart.Symbol#setFillThickness setFillThickness
070 *
071 *
072 **/
073 public interface GChartCanvasLite {
074 /**
075 * Draws an arc. If the context has a non-empty path, then the method must add a
076 * straight line from the last point in the path to the start point of the arc.
077 *
078 * @param x center X coordinate
079 * @param y center Y coordinate
080 * @param radius radius of drawn arc
081 * @param startAngle angle measured from positive X axis to start of arc CW
082 * @param endAngle angle measured from positive X axis to end of arc CW
083 * @param antiClockwise direction that the arc line is drawn
084 */
085 public void arc(double x, double y, double radius, double startAngle, double endAngle, boolean antiClockwise);
086 /**
087 * Erases the current path and prepares it for a new path.
088 */
089 public void beginPath();
090 /**
091 * Clears the entire canvas.
092 */
093 public void clear();
094 /**
095 * Closes the current path. "Closing" simply means that a line is drawn
096 * from the last element in the path back to the first.
097 */
098 public void closePath();
099 /**
100 * Fills the current path according to the current fillstyle.
101 */
102 public void fill();
103 /**
104 * Adds a line from the last point in the current path to the
105 * point defined by x and y.
106 *
107 * @param x x coord of point
108 * @param y y coord of point
109 */
110 public void lineTo(double x, double y);
111 /**
112 * Makes the last point in the current path be <b>(x,y)</b>.
113 *
114 * @param x x coord of point
115 * @param y y coord of point
116 */
117 public void moveTo(double x, double y);
118
119 /**
120 * Resizes the canvas.
121 *
122 * @param width width of canvas drawing area in pixels
123 * @param height height of canvas drawing area in pixels
124 *
125 */
126 public void resize(int width, int height);
127 /**
128 * Set the current Fill Style to the specified color.
129 * <p>
130 *
131 * Whenever GChart uses canvas to fill-in a symbol's interior (e.g.
132 * the interior part, excluding the border, of a solid-fill pie
133 * slice), it passes the symbol's canvas fill style string (which is
134 * specified via <tt>Symbol.setBackgroundColor</tt>) to this method.
135 * It then uses the <tt>fill</tt> method of this interface to fill in
136 * the symbol's interior with this color.
137 *
138 * <p>
139 *
140 * Your method should be able to handle any color specification
141 * string likely to be passed into
142 * <tt>Symbol.setBackgroundColor</tt>, see that method for full
143 * details for the kinds of strings that are supported.
144 *
145 * @see GChart.Symbol#setBackgroundColor setBackgroundColor
146 * @see #fill fill
147 *
148 * @param canvasFillStyle the fill style specification string. You may
149 * assume that GChart will pass you either a standard CSS color
150 * specification string, or an RGBA extension of this
151 * standard CSS format, such as <tt>rgba(255,255,255,0.5)</tt>.
152 *
153 */
154 public void setFillStyle(String canvasFillStyle);
155 /**
156 * Sets the current context's linewidth. Line width is the thickness
157 * of a stroked line.
158 * <p>
159 *
160 * GChart will obtain the width's passed into this method from those
161 * specified by the <tt>Symbol.setBorderWidth</tt> method (which
162 * defines the widths of stroked borders around any canvas-rendered
163 * line, area, or pie-slice chart elements) and from the
164 * <tt>Symbol.setFillThickness</tt> method (which defines the
165 * thickness of a line chart's connecting lines).
166 *
167 * <p>
168 *
169 * @see GChart.Symbol#setBorderWidth setBorderWidth
170 * @see GChart.Symbol#setFillThickness setFillThickness
171 *
172 * @param width the width of the stroked line, in pixels
173 */
174 public void setLineWidth(double width);
175 /**
176 * Set the current Stroke Style to the specified color.
177 *
178 * <p>
179 *
180 * GChart will obtain the color strings passed into this method
181 * from those specified by the <tt>Symbol.setBorderColor</tt>
182 * method. You can assume that these strings will be either in
183 * standard CSS or the extended RGBA format, see
184 * <tt>Symbol.setBorderColor</tt> for full details. These
185 * colors will become the colors of the stroked borders around
186 * any canvas-rendered line, area, or pie-slice chart elements.
187 *
188 *
189 * <p>
190 *
191 * @see GChart.Symbol#setBorderColor setBorderColor
192 * @see #stroke stroke
193 *
194 * @param canvasStrokeStyle the stroke style specification string.
195 * You may assume that, during rendering, GChart will pass you either
196 * a standard CSS color specification string, or an RGBA
197 * extension of this standard CSS format such as
198 * <tt>rgba(255,255,255,0.5)</tt> for semi-transparent white.
199 *
200 *
201 */
202 public void setStrokeStyle(String canvasStrokeStyle);
203 /**
204 * Strokes the current path according to the current stroke style.
205 */
206 public void stroke();
207 }
208