/*******************************************************************************
 * Copyright (c) 2004 IBM Corporation 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:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.wst.command.internal.env.ui.widgets;

import org.eclipse.core.runtime.IStatus;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Listener;


/**
 * This interface provides a way for developers to create validatable widgets
 * that can be used in many different Eclipse UI contexts. (ie. in a Windows, Diaglogs,
 * wizard pages, etc)
 *
 * The main functionality this interface has over just a regular Eclipse Composite
 * is that it provides a mechanism for validating the Widget.  When validating
 * there are two aspects to keep in mind.  The first aspect deals with WHEN validation
 * occurs and the second aspect deals with WHAT to do for a validation event.
 * 
 * The first aspect of triggering validation events is handled by the statusListener
 * parameter of the addControls method.  If a particular control that is contributed can
 * affect the validity of this WidgetContributor then the statusListener object
 * should be added to the listener list of that control.  For example, if the text in
 * a Text widget can affect the validity of this WidgetContributor then you would
 * add the statusListener to the Text widgets Modify listener list:
 * 
 * 
 *   Text someText = new Text( parent, SWT.NONE );
 *   someText.addListener( SWT.Modify, statusListener );
 * 
 * Note: if you want to force validation of this widget you can call
 *       the statusListener.handleEvent(null) method directly.  This
 *       is not the prefered may to trigger validation, however.
 *       
 * The second aspect of valiation is what to do when the validation event occurs.
 * This is handled by getStatus method.  Any code that ensures that this widget is
 * valid should be put in the getStatus implementation. 
 * 
 * 
*/
public interface WidgetContributor 
{
  /**
   * This method should be used to implement the UI contributions for this widget.
   * 
   * @param parent The composite parent that sub widgets should use.
   * @param statusListener This listener should be added to any widget that can
   *                       affect the validity of this WidgetContributor.
   * @return returns a WidgetDataEvents object.  This object is used by the
   *         framework to internalize and externalize data for this widget.
   */
  public WidgetDataEvents addControls( Composite parent, Listener statusListener );
  
  /**
   * This method should implement validation code for this WidgetContributor.
   * 
   * @return returns a status object indicating the validity of this widget.
   *         If the status severity is ERROR then this widget is considered to
   *         be invalid.  For any other status severity or if the status returned
   *         is null this widget is considered to be valid.
   */
  public IStatus getStatus();
}