/*******************************************************************************
 * Copyright (c) 2000, 2003 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials 
 * are 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:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.ui.views.properties;

import org.eclipse.jface.viewers.CellEditor;
import org.eclipse.swt.graphics.Image;
import org.eclipse.swt.widgets.Composite;
/**
 * <code>IPropertySheetEntry</code> describes the model interface for the
 * property sheet.
 * <p>
 * May be implemented when supplying a custom root entry
 * to a property page.
 * </p>
 */
public interface IPropertySheetEntry {
	/**
	 * The filter id for expert properties
	 */
	public String FILTER_ID_EXPERT = "org.eclipse.ui.views.properties.expert"; //$NON-NLS-1$
/**
 * Adds the given listener to this entry's collection
 * of listeners.
 *
 * @param listener the listener to add
 */
public void addPropertySheetEntryListener(IPropertySheetEntryListener listener);
/**
 * Apply the current cell editor value.
 */
public void applyEditorValue();
/**
 * Called when the entry is no longer needed
 */
public void dispose();
/**
 * Returns the entry's category.
 *
 * @return the entry's category
 */
public String getCategory();
/**
 * Returns the child entries for this entry.
 *
 * @return the child entries for this entry
 */
public IPropertySheetEntry[] getChildEntries();
/**
 * Return a short description of the property sheet entry.
 * Typically this description is shown in a status line
 * when the entry is selected.
 *
 * @return the entry's description
 */
public String getDescription();
/**
 * Returns the name used to display the property.
 *
 * @return the name used to display the property
 */
public String getDisplayName();
/**
 * Return the <code>CellEditor</code> used to edit the property.
 *
 * @param parent the parent widget for the editor
 * @return the <code>CellEditor</code> used to edit the property
 */
CellEditor getEditor(Composite parent);
/**
 * Returns the error text to display if the value is invalid. 
 *
 * @return the error text to display when the value is invalid
 * or <code>null</code>
 */
public String getErrorText();
/**
 * Return the filter ids used to group entries into levels such as Expert.
 * Valid values are defined as constants on this interface.
 *
 * @return the filter ids used to group entries into levels such as Expert.
 */
public String[] getFilters();
/**
 * Returns the help context id for this entry,
 * or <code>null</code> if this entry has no help context id.
 * <p>
 * NOTE: Help support system API's changed since 2.0 and arrays
 * of contexts are no longer supported.
 * </p>
 * <p>
 * Thus the only valid non-<code>null</code> return type for this method
 * is a <code>String</code> representing a context id. The previously
 * valid return types are deprecated. The plural name for this method
 * is unfortunate.
 * </p>
 * 
 * @return the help context id for this entry
 */
public Object getHelpContextIds();
/**
 * Returns the image for the property value, if there is one.
 * This image is managed by the entry it came from.  Callers
 * of this method must never dispose the returned image.
 *
 * @return the image for this property value or <code>null</code>
 */
public Image getImage();
/**
 * Returns the value of the objects expressed as a String.
 *
 * @return the value of the objects expressed as a String
 */
public String getValueAsString();
/**
 * Returns <code>true</code> if the entry has children.
 *
 * @return <code>true</code> if the entry has children
 */
public boolean hasChildEntries();
/**
 * Removes the given listener from this entry's collection
 * of listeners.
 *
 * @param listener the listener to remove
 */
public void removePropertySheetEntryListener(IPropertySheetEntryListener listener);
/**
 * Resets the property value to its default value if it has been changed.
 */
void resetPropertyValue();
/*
 * Sets the objects which represent the property values for
 * this entry. In the case of the root entry these objects
 * are the input to the viewer.
 *
 * @param values the values for this entry
 */
public void setValues(Object[] values);
}