001 /* Copyright 2007,2008,2009 John C. Gunther
002 *
003 * Licensed under the Apache License, Version 2.0 (the
004 * "License"); you may not use this file except in compliance
005 * with the License. You may obtain a copy of the License at:
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing,
010 * software distributed under the License is distributed on an
011 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
012 * either express or implied. See the License for the specific
013 * language governing permissions and limitations under the
014 * License.
015 */
016 package com.googlecode.gchart.client;
017
018 /**
019 * Defines the extra features that must be added to a <tt>Widget</tt>
020 * before it can be used to generate hover feedback. You can customize
021 * a curve's hover feedback by passing a <tt>Widget</tt> that
022 * implements this interface to the <tt>setHoverWidget</tt> method.
023 * <p>
024 *
025 * For example, the chart below uses a <tt>HoverUpdateable Button</tt>
026 * to both display each point's x,y position, and allow the user to
027 * delete that point (This is Chart #18 in the Chart Gallery. As with
028 * all of these example charts, you'll
029 * need to add the chart to the <tt>RootPanel</tt> and then invoke
030 * the <tt>update</tt> method, as shown in the typical GChart
031 * boilerplate <a
032 * href="package-summary.html#typicalgchartboilerplate">code snippet</a>
033 * to get this example to actually work).
034 *
035 *
036 * {@code.sample
037 * ..\..\..\..\..\..\gcharttestapp\src\com\googlecode\gchart\gcharttestapp\client\GChartExample18.java}
038 *
039 * <p>
040 *
041 * Here's what this chart looks like with the user hovering over the
042 * point at <tt>(5, 10)</tt>, before they have deleted anything:
043 *
044 *
045 * <p>
046 *
047 * <img
048 * src="{@docRoot}/com/googlecode/gchart/client/doc-files/gchartexample18.png">
049 *
050 * <p>
051 *
052 * <i>Tip</i>: If you just need to generate custom HTML that varies
053 * with the hovered over point, it's probably easier to use
054 * a <tt>HoverParameterInterpreter</tt> rather than a
055 * <tt>HoverUpdateable</tt> widget.
056 *
057 *
058 * @see GChart.Symbol#setHoverWidget setHoverWidget
059 * @see GChart.Symbol#setHoverLocation setHoverLocation
060 * @see GChart.Symbol#setHoverAnnotationSymbolType setHoverAnnotationSymbolType
061 * @see GChart.Symbol#setHoverXShift setHoverXShift
062 * @see GChart.Symbol#setHoverYShift setHoverYShift
063 * @see HoverParameterInterpreter HoverParameterInterpreter
064 *
065 */
066
067 public interface HoverUpdateable {
068
069 /**
070 * Frees any resources that the <tt>hoverUpdate</tt> method may have
071 * allocated when the user first hovered over the point,
072 * thus returning the hoverWidget to a well-defined state:
073 * ready to recieve the next <tt>hoverUpdate</tt>
074 * without errors, memory leaks, etc.
075 * <p>
076 *
077 * You might think of this method an an "undo" for
078 * this interface's <tt>hoverUpdate</tt> method.
079 *
080 * <p>
081 *
082 * GChart calls this method whenever the mouse moves away
083 * from a point it was previously hovering over (just before
084 * it hides the hover annotation and removes the hover
085 * selection feedback from that point).
086 *
087 * <p>
088 *
089 * For example, a hover widget that contains a nested
090 * <tt>MenuBar</tt> might
091 * need to call <tt>setVisible(false)</tt> on any opened submenus,
092 * because programatically making the main menu invisible (which
093 * GChart will do automatically when you move away from the point)
094 * does <i>not</i>, as you might have expected, hide all opened
095 * sub-menus. Another possible use for this method is to commit a
096 * series of changes the user made via a form-like hover widget when
097 * the user implicitly "closes" the hover widget by moving the mouse
098 * away from the point (when it makes sense, it's best to commit such changes
099 * on-the-fly, to avoid the potential for lost work).
100 * <p>
101 *
102 * Note that GChart automatically removes (when
103 * <tt>optimizeFormMemory</tt> is true) or makes invisible (when it's
104 * false) the DOM representation of the hover widget when the mouse
105 * moves away from the hovered over point. So, all you need to worry
106 * about is cleaning up any artifacts generated by this widget's
107 * <tt>hoverUpdate</tt> method.
108 * <p>
109 *
110 *
111 * <i>Tip</i>: Most hover widgets, such as those that simply display
112 * information about the hovered over point, don't have anything
113 * that needs to be cleaned up, and thus can just use a do-nothing
114 * <tt>hoverCleanup</tt> method:
115 * <p>
116 *
117 * <pre>
118 * public void hoverCleanup(Curve.Point hoveredAwayFrom) {}
119 * </pre>
120 *
121 * @param hoveredAwayFrom the previously hovered over point that the
122 * user has just moved the mouse away from (and thus is no
123 * longer hovering over).
124 *
125 * @see #hoverUpdate hoverUpdate
126 *
127 */
128 public void hoverCleanup(GChart.Curve.Point hoveredAwayFrom);
129
130 /** Updates this widget so that it displays appropriate
131 information about the given point.
132
133 <p>
134
135 GChart will call this method, as needed, to assure that the hover
136 widget always displays information about the point that the user
137 is currently "touching" with the mouse (the "hovered over" point).
138 In particular, GChart calls <tt>hoverUpdate</tt> when the mouse
139 first hovers over a point, but it won't call it again if you move
140 the mouse in a way that keeps it hovering over that same point.
141
142 <p>
143
144 Note that whenever a point's hover annotation (e.g. hover widget)
145 becomes visible, the hit test region for that point is in effect
146 extended to include the rectangular box associated with its hover
147 annotation. This policy creates a "sticky open" feel to hover
148 widgets. Applications that allow the user to interact with the
149 hover widget need to arrange for a "mousemove pathway" (by using
150 methods such as <tt>setBrushSize</tt> and
151 <tt>setHoverAnnotationSymbolType(ANCHOR_MOUSE)</tt> ) that allows
152 the user to move the mouse into the hover widget without moving
153 away from the hovered over point (which would otherwise dismiss
154 the hover annotation before the user could interact with it).
155
156 <p>
157
158
159 This method only needs to concern itself with the content and/or
160 size of the widget; GChart will position and change the visibility
161 of the widget appropriately (as defined via the
162 <tt>setHoverLocation</tt>, <tt>setHoverAnnotationSymbolType</tt>,
163 <tt>setHoverXShift</tt> and <tt>setHoverYShift</tt> methods) as
164 the user moves the mouse over different points on the chart.
165
166 @param hoveredOver a reference to the point that the mouse
167 has just begun hovering over.
168 <p>
169
170 @see #hoverCleanup hoverCleanup
171 @see GChart.Symbol#setHoverLocation setHoverLocation
172 @see GChart.Symbol#setHoverAnnotationSymbolType setHoverAnnotationSymbolType
173 @see GChart.Symbol#setHoverXShift setHoverXShift
174 @see GChart.Symbol#setHoverYShift setHoverYShift
175 @see GChart.Symbol#setBrushSize setBrushSize
176
177 */
178
179 public void hoverUpdate(GChart.Curve.Point hoveredOver);
180
181
182 }