001    // Copyright 2004, 2005 The Apache Software Foundation
002    //
003    // Licensed under the Apache License, Version 2.0 (the "License");
004    // you may not use this file except in compliance with the License.
005    // 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, software
010    // distributed under the License is distributed on an "AS IS" BASIS,
011    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012    // See the License for the specific language governing permissions and
013    // limitations under the License.
014    
015    package org.apache.tapestry.form;
016    
017    /**
018     * Used by a {@link PropertySelection} to provide labels for options.
019     * <p>
020     * The component requires three different representations of each option:
021     * <ul>
022     * <li>The option value, the server-side Java object that will eventually be assigned to a property
023     * <li>The label, a string which is incorprated into the HTML to identify the option to the user
024     * <li>The value, a client-side string which is used to represent the option as the value of the
025     * &lt;option&gt; or &lt;input type=radio&gt; generated by the {@link PropertySelection}.
026     * </ul>
027     * <p>
028     * The option is usually a string, a primitive value, or some kind of business object. The label is
029     * often a property of the option object (for example, for a list of customers, it could be the
030     * customer name).
031     * <p>
032     * It should be easy to convert between the value and the option. It may simply be an index into an
033     * array. For business objects, it is often the primary key of the object, expressed as a String.
034     * 
035     * @author Howard Lewis Ship
036     */
037    
038    public interface IPropertySelectionModel
039    {
040        /**
041         * Returns the number of possible options.
042         */
043    
044        int getOptionCount();
045    
046        /**
047         * Returns one possible option that will be assigned to the server-side property.
048         */
049    
050        Object getOption(int index);
051    
052        /**
053         * Returns the label for an option. It is the responsibility of the adaptor to make this value
054         * localized.
055         */
056    
057        String getLabel(int index);
058    
059        /**
060         * Returns a String used to represent the option in the HTML (as the value of an &lt;option&gt;
061         * or &lt;input type=radio&gt;. This value is not visible to the user, and is often an index
062         * into an array.
063         */
064    
065        String getValue(int index);
066    
067        /**
068         * Used to help rendering of options that should be marked with the html <code>disabled</code>
069         * attribute.
070         * 
071         * @param index The option to check.
072         * @return True if the option shouldn't be selectable, false otherwise.
073         */
074        boolean isDisabled(int index);
075        
076        /**
077         * Returns the option corresponding to a value. This is used when interpreting submitted form
078         * parameters.
079         */
080    
081        Object translateValue(String value);
082    }