package net.sourceforge.phpdt.externaltools.variable;

/**********************************************************************
 Copyright (c) 2002 IBM Corp. and others. All rights reserved.
 This file is made available under the terms of the Common Public License v1.0
 which accompanies this distribution, and is available at
 http://www.eclipse.org/legal/cpl-v10.html
 �
 Contributors:
 **********************************************************************/

import net.sourceforge.phpdt.externaltools.group.IGroupDialogPage;

import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Control;

/**
 * Represents the API for a client extending one of the variable extension
 * points to provide visual editing of the variable.
 * <p>
 * This interface is not to be extended by clients. Clients may implement this
 * interface.
 * </p>
 */
public interface IVariableComponent {
	/**
	 * Returns the control to edit the variable value, otherwise
	 * <code>null</code> if no editing supported or if
	 * <code>createContents</code> has not been called yet
	 * 
	 * @return the main control for the variable component or <code>null</code>
	 *         if none
	 */
	public Control getControl();

	/**
	 * Creates the control to edit the variable. Does nothing if no editing
	 * supported.
	 * 
	 * @param parent
	 *            the composite to parent all controls to
	 * @param varTag
	 *            the variable tag name to create the controls for
	 * @param page
	 *            the dialog page this visual component will be part of
	 */
	public void createContents(Composite parent, String varTag,
			IGroupDialogPage page);

	/**
	 * Returns the variable value as specified by the user thru the visual
	 * component.
	 * 
	 * @return the variable value as indicated by the visual component
	 */
	public String getVariableValue();

	/**
	 * Returns whether the variable's visual component has an acceptable value.
	 * 
	 * @return <code>true</code> if all value acceptable, or
	 *         <code>false</code> otherwise
	 */
	public boolean isValid();

	/**
	 * Sets the visual component to represent the given variable value.
	 * 
	 * @param varValue
	 *            the variable value the visual component should indicate
	 */
	public void setVariableValue(String varValue);

	/**
	 * Validates visual component current values entered by the user and updates
	 * it's valid state if needed
	 */
	public void validate();
}