// This Source Code is in the Public Domain per: http://unlicense.org
package org.litesoft.GWT.client.widgets.datatables;

/**
 * Defines methods for converting model values to displayable Strings and vice versa.
 *
 * @see <a href="http://developer.apple.com/documentation/Cocoa/Reference/Foundation/Classes/NSFormatter_Class/Reference/Reference.html">AppKit NSFormatter</a>
 */
public interface StringFormatter
{
    /*
       * TODO: add getAttributedString() or getRenderingHints() to enable, for
       * example, negative values to be rendered in red?
       */

    /**
     * Get the String value to be displayed in a view cell. Strings typically
     * <em>cannot</em> contain html markup.
     *
     * @param modelElement the model element being displayed
     *
     * @return the String representation of <code>modelElement</code>
     */
    String getString( Object modelElement );

    /**
     * Get the String value to be displayed in the cell editor. E.g. a financial
     * application may add a currency symbol for viewing, but the cell editor
     * uses numeric values only.
     *
     * @param modelElement
     *
     * @return a String, or <code>null</code> to use the
     *         {@link #getString(Object)} value
     */
    String getEditingString( Object modelElement );
}