/*******************************************************************************
 * Copyright (c) 2005, 2009 Symbian Ltd and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 * Symbian Ltd - Initial API and implementation
 *******************************************************************************/
package org.eclipse.cdt.managedbuilder.core;

/**
 * This interface represents an option value handler in the managed build
 * system. It is used to enable a tool integrator to use the MBS configuration
 * GUI, while linking to an alternative back-end.
 * 
 * @since 3.0
 */
public interface IManagedOptionValueHandler {

	/**
	 * The option is opened, i.e. its UI element is created. The valueHandler
	 * can override the value of the option. If it does not, the last persisted
	 * value is used.
	 */
	public final int EVENT_OPEN = 1;

	/**
	 * The option is closed. i.e. its value has been destroyed when a
	 * configuration/resource gets deleted. The value handler can do various
	 * things associated with destroying the option such as freeing the memory
	 * associated with this option callback, if needed.
	 */
	public final int EVENT_CLOSE = 2;

	/**
	 * The default value option::defaultValue has been set. The handleValue
	 * callback is called afterwards to give the handler a chance to override
	 * the value or to update the value in its back-end. Typically this event
	 * will be called when the Restore Defaults button is pressed.
	 */
	public final int EVENT_SETDEFAULT = 3;

	/**
	 * The option has been set by pressing the Apply button (or the OK button).
	 * The valueHandler can transfer the value of the option to its own
	 * back-end.
	 */
	public final int EVENT_APPLY = 4;

	/**
	 * Posted when the managed build extensions (defined in the manifest files)
	 * are loaded. The handler is allowed to adjust the extension elements
	 */
	public final int EVENT_LOAD = 5;

	/**
	 * Handles transfer between values between UI element and back-end in
	 * different circumstances.
	 * 
	 * @param configuration
	 *            build configuration of option (may be IConfiguration or
	 *            IResourceConfiguration)
	 * @param holder
	 *            contains the holder of the option
	 * @param option
	 *            the option that is handled
	 * @param extraArgument
	 *            extra argument for handler
	 * @param event
	 *            event to be handled
	 * 
	 * @return True when the event was handled, false otherwise. This enables
	 *         default event handling can take place.
	 */
	boolean handleValue(IBuildObject configuration, IHoldsOptions holder,
			IOption option, String extraArgument, int event);

	/**
	 * Checks whether the value of an option is its default value.
	 * 
	 * @param configuration
	 *            build configuration of option (may be IConfiguration or
	 *            IResourceConfiguration)
	 * @param holder
	 *            contains the holder of the option
	 * @param option
	 *            the option that is handled
	 * @param extraArgument
	 *            extra argument for handler
	 * 
	 *            The additional options besides configuration are supplied to
	 *            provide enough information for querying the default value from
	 *            a potential data storage back-end.
	 * 
	 * @return True if the options value is its default value and False
	 *         otherwise. This enables that default event handling can take
	 *         place.
	 */
	boolean isDefaultValue(IBuildObject configuration, IHoldsOptions holder,
			IOption option, String extraArgument);

	/**
	 * Checks whether an enumeration value of an option is currently a valid
	 * choice. The use-case for this method is the case, where the set of valid
	 * enumerations in the plugin.xml file changes. The UI will remove entries
	 * from selection lists if the value returns false.
	 * 
	 * @param configuration
	 *            build configuration of option (may be IConfiguration or
	 *            IResourceConfiguration)
	 * @param holder
	 *            contains the holder of the option
	 * @param option
	 *            the option that is handled
	 * @param extraArgument
	 *            extra argument for handler
	 * @param enumValue
	 *            enumeration value that is to be checked
	 * 
	 *            The additional options besides configuration are supplied to
	 *            provide enough information for querying information from a a
	 *            potential data storage back-end.
	 * 
	 * @return True if the enumeration value is valid and False otherwise.
	 */
	boolean isEnumValueAppropriate(IBuildObject configuration,
			IHoldsOptions holder, IOption option, String extraArgument,
			String enumValue);
}
