/*
 *    GeoTools - The Open Source Java GIS Toolkit
 *    http://geotools.org
 * 
 *    (C) 2004-2008, Open Source Geospatial Foundation (OSGeo)
 *
 *    This library is free software; you can redistribute it and/or
 *    modify it under the terms of the GNU Lesser General Public
 *    License as published by the Free Software Foundation;
 *    version 2.1 of the License.
 *
 *    This library is distributed in the hope that it will be useful,
 *    but WITHOUT ANY WARRANTY; without even the implied warranty of
 *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *    Lesser General Public License for more details.
 */
package org.geotools.renderer.lite;

import java.awt.Graphics2D;
import java.awt.Rectangle;
import java.awt.geom.Rectangle2D;
import java.util.List;

import org.geotools.geometry.jts.LiteShape2;
import org.geotools.styling.TextSymbolizer;
import org.geotools.util.NumberRange;
import org.opengis.feature.simple.SimpleFeature;

/**
 * Used to cache labels prior to their being drawn on the screen.
 * <p>
 * Implementations exisit with different trade offs about what labels can fit where.
 * 
 * @author jeichar
 * @since 2.2
 * @source $URL: http://svn.osgeo.org/geotools/tags/2.7-M3/modules/library/render/src/main/java/org/geotools/renderer/lite/LabelCache.java $
 */
public interface LabelCache {
    /**
     * Called by renderer to indicate that the rendering process is starting.
     */
    void start();
    
    /**
     * Called by renderer to indication the start of rendering a layer.  Will add the layer to the
     * set of active layers.
     * 
     * @param layerId an id for the layer
     */
    void startLayer(String layerId);
    
    /**
     * Puts a Label in the cache.
     * 
     * @param layerId  id indicating the layer the feature is part of
     * @param symbolizer The symbolizer containing the style information
     * @param feature the feature that has the information required for the symbolizer to 
     * calculate the required render information. 
     * @param shape the shape to be labeled.  This is in screen coordinates.
     * @param scaleRange the scaleRange that the symbolizer is legal
     */
    void put( String layerId, TextSymbolizer symbolizer, SimpleFeature feature, LiteShape2 shape, NumberRange<Double> scaleRange) ;

    /**
     * Reserve the provided geometry prior to sorting out where labels can go.
     * <p>
     * This facility is used to reserve an area so that labels do not end up
     * overlapping on screen constructs like scalebars or north arrows etc...
     * 
     * @param Geometry The Area of the screen to reserve (in screen coordinates)
     */
    void put( Rectangle2D geometry );
    
    /**
     * Called to indicate that a layer is done rendering.  The method may draw labels if appropriate
     * for the labeling algorithm 
     * 
     * @param graphics the graphics to draw on.
     * @param displayArea The size of the display area
     * @param layerId an id for the layer
     */
    void endLayer(String layerId, Graphics2D graphics, Rectangle displayArea);
    
    /**
     * Called to indicate that the map is done rendering.  The method may draw labels if appropriate
     * for the labeling algorithm 
     * 
     * @param graphics the graphics to draw on.
     * @param displayArea The size of the display area.
     */
    void end(Graphics2D graphics, Rectangle displayArea);
    
    /**
     * Tells the cache to stop labelling.  
     */
    void stop();
    
    /**
     * Clears the cache completely 
     */
    public void clear();
    
    /**
     * Clears the cache of all information relating to the layer identified.
     * @param layerId id of the layer
     */
    public void clear(String layerId);
    
    /**
     * Leaves the label information in the cache but ignores it when calculating what labels are drawn.
     * 
     * @param layerId id of the layer to disable.
     */
    public void disableLayer(String layerId);
    
    /**
     * Enable a layer after being disabled.  If startLayer is called this does not need to be called
     * as start layer implicitely activates the layer.
     * 
     * @param layerId layer to activate.
     */
    public void enableLayer(String layerId);
    
    /**
     * Return a list with all the values in priority order.  Both grouped and non-grouped
     * @param labelCache
     * @return list with all values in priority order
     */
    public List orderedLabels();
}