com.googlecode.gchart.client
Interface HoverUpdateable

public interface HoverUpdateable

Defines the extra features that must be added to a Widget before it can be used to generate hover feedback. You can customize a curve's hover feedback by passing a Widget that implements this interface to the setHoverWidget method.

For example, the chart below uses a HoverUpdateable Button to both display each point's x,y position, and allow the user to delete that point (This is Chart #18 in the Chart Gallery. As with all of these example charts, you'll need to add the chart to the RootPanel and then invoke the update method, as shown in the typical GChart boilerplate code snippet to get this example to actually work).

package com.googlecode.gchart.gcharttestapp.client;
import com.google.gwt.event.dom.client.ClickEvent;
import com.google.gwt.event.dom.client.ClickHandler;
import com.google.gwt.user.client.ui.Button;
import com.googlecode.gchart.client.GChart;
import com.googlecode.gchart.client.HoverUpdateable;

/**
 *
 * This chart allows the user to delete the hovered-over
 * point, by using a <tt>HoverUpdateable</tt> Button.
 * 
 */
public class GChartExample18 extends GChart {
   class HoverUpdateableButton extends Button
         implements HoverUpdateable {
      public void hoverUpdate(Curve.Point hoveredOver) {
         setText(hoveredOver.getHovertext()); 
      }
      public void hoverCleanup(Curve.Point hoveredAwayFrom){}
   }
   
   GChartExample18() {
     setChartSize(300, 300);
     setBorderStyle("none");

     // add a simple y = 2*x curve
     addCurve();
     getCurve().getSymbol().setHeight(30);
     getCurve().getSymbol().setWidth(30);
     getCurve().getSymbol().setBorderWidth(3);     
     for (int iPoint = 0; iPoint < 10; iPoint++) 
        getCurve().addPoint(iPoint, 2*iPoint);
   
     // pop-up delete button centered on hovered over point
     HoverUpdateableButton deletePoint =
        new HoverUpdateableButton();
     deletePoint.addClickHandler(new ClickHandler() {
        public void onClick(ClickEvent event) {
           getTouchedCurve().removePoint(getTouchedPoint());
           update();
        }
     });
     getCurve().getSymbol().setHoverWidget(deletePoint);
     getCurve().getSymbol().setHoverLocation(
        AnnotationLocation.CENTER);
     getCurve().getSymbol().setHovertextTemplate(
        "Delete (${x}, ${y})");     
   }
   
}

Here's what this chart looks like with the user hovering over the point at (5, 10), before they have deleted anything:

Tip: If you just need to generate custom HTML that varies with the hovered over point, it's probably easier to use a HoverParameterInterpreter rather than a HoverUpdateable widget.

See Also:

setHoverWidget, setHoverLocation, setHoverAnnotationSymbolType, setHoverXShift, setHoverYShift, HoverParameterInterpreter

Method Summary

void	hoverCleanup(GChart.Curve.Point hoveredAwayFrom) Frees any resources that the hoverUpdate method may have allocated when the user first hovered over the point, thus returning the hoverWidget to a well-defined state: ready to recieve the next hoverUpdate without errors, memory leaks, etc.
void	hoverUpdate(GChart.Curve.Point hoveredOver) Updates this widget so that it displays appropriate information about the given point.

Method Detail

hoverCleanup

void hoverCleanup(GChart.Curve.Point hoveredAwayFrom)

Frees any resources that the hoverUpdate method may have allocated when the user first hovered over the point, thus returning the hoverWidget to a well-defined state: ready to recieve the next hoverUpdate without errors, memory leaks, etc.

You might think of this method an an "undo" for this interface's hoverUpdate method.

GChart calls this method whenever the mouse moves away from a point it was previously hovering over (just before it hides the hover annotation and removes the hover selection feedback from that point).

For example, a hover widget that contains a nested MenuBar might need to call setVisible(false) on any opened submenus, because programatically making the main menu invisible (which GChart will do automatically when you move away from the point) does not, as you might have expected, hide all opened sub-menus. Another possible use for this method is to commit a series of changes the user made via a form-like hover widget when the user implicitly "closes" the hover widget by moving the mouse away from the point (when it makes sense, it's best to commit such changes on-the-fly, to avoid the potential for lost work).

Note that GChart automatically removes (when optimizeFormMemory is true) or makes invisible (when it's false) the DOM representation of the hover widget when the mouse moves away from the hovered over point. So, all you need to worry about is cleaning up any artifacts generated by this widget's hoverUpdate method.

Tip: Most hover widgets, such as those that simply display information about the hovered over point, don't have anything that needs to be cleaned up, and thus can just use a do-nothing hoverCleanup method:

   public void hoverCleanup(Curve.Point hoveredAwayFrom) {}
 

Parameters:

hoveredAwayFrom - the previously hovered over point that the user has just moved the mouse away from (and thus is no longer hovering over).

See Also:

hoverUpdate

hoverUpdate

void hoverUpdate(GChart.Curve.Point hoveredOver)

Updates this widget so that it displays appropriate information about the given point.

GChart will call this method, as needed, to assure that the hover widget always displays information about the point that the user is currently "touching" with the mouse (the "hovered over" point). In particular, GChart calls hoverUpdate when the mouse first hovers over a point, but it won't call it again if you move the mouse in a way that keeps it hovering over that same point.

Note that whenever a point's hover annotation (e.g. hover widget) becomes visible, the hit test region for that point is in effect extended to include the rectangular box associated with its hover annotation. This policy creates a "sticky open" feel to hover widgets. Applications that allow the user to interact with the hover widget need to arrange for a "mousemove pathway" (by using methods such as setBrushSize and setHoverAnnotationSymbolType(ANCHOR_MOUSE) ) that allows the user to move the mouse into the hover widget without moving away from the hovered over point (which would otherwise dismiss the hover annotation before the user could interact with it).

This method only needs to concern itself with the content and/or size of the widget; GChart will position and change the visibility of the widget appropriately (as defined via the setHoverLocation, setHoverAnnotationSymbolType, setHoverXShift and setHoverYShift methods) as the user moves the mouse over different points on the chart.

Parameters:

hoveredOver - a reference to the point that the mouse has just begun hovering over.

See Also:

hoverCleanup, setHoverLocation, setHoverAnnotationSymbolType, setHoverXShift, setHoverYShift, setBrushSize