/*******************************************************************************
 * Copyright (c) 2000, 2010 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.ui;

import org.eclipse.core.runtime.content.IContentType;
import org.eclipse.jface.resource.ImageDescriptor;

/**
 * Registry of editors known to the workbench.
 * <p>
 * An editor can be created in one of two ways:
 * <ul>
 *   <li>An editor can be defined by an extension to the workbench.</li>
 *   <li>The user manually associates an editor with a given resource extension
 *      type. This will override any default workbench or platform association.
 *      </li>
 * </ul>
 * </p>
 * <p>
 * The registry does not keep track of editors that are "implicitly" determined.
 * For example a bitmap (<code>.bmp</code>) file will typically not have a 
 * registered editor. Instead, when no registered editor is found, the 
 * underlying OS is consulted.
 * </p>
 * <p>
 * This interface is not intended to be implemented by clients.
 * </p>
 * 
 * @see org.eclipse.ui.IWorkbench#getEditorRegistry()
 * @since 1.0
 * @noimplement This interface is not intended to be implemented by clients.
 */
public interface IEditorRegistry {

    /**
     * The property identifier for the contents of this registry.
     */
    public static final int PROP_CONTENTS = 0x01;

    /**
     * The identifier for the system external editor descriptor. This descriptor 
     * is always present in the registry on all platforms.
     * This editor requires an input which implements
     * {@link org.eclipse.ui.IPathEditorInput IPathEditorInput}.
     * Use {@link #findEditor findEditor} to access the editor descriptor for
     * this identifier.
     * 
     */
    public static final String SYSTEM_EXTERNAL_EDITOR_ID = "org.eclipse.ui.systemExternalEditor"; //$NON-NLS-1$

    /**
     * The identifier for the system in-place editor descriptor. This descriptor 
     * is only present in the registry on platforms that support in-place editing
     * (for example Win32). This editor requires an input which implements
     * {@link org.eclipse.ui.IInPlaceEditorInput IInPlaceEditorInput}. Use 
     * {@link #findEditor findEditor} to access the editor descriptor for this
     * identifier.
     * 
     */
    public static final String SYSTEM_INPLACE_EDITOR_ID = "org.eclipse.ui.systemInPlaceEditor"; //$NON-NLS-1$

    /**
     * Adds a listener for changes to properties of this registry.
     * Has no effect if an identical listener is already registered.
     * <p>
     * The properties ids are as follows:
     * <ul>
     *   <li><code>PROP_CONTENTS</code>: Triggered when the file editor mappings in
     *       the editor registry change.</li>
     * </ul>
     * </p>
     *
     * @param listener a property listener
     */
    public void addPropertyListener(IPropertyListener listener);

    /**
     * Finds and returns the descriptor of the editor with the given editor id.
     *
     * @param editorId the editor id
     * @return the editor descriptor with the given id, or <code>null</code> if not
     *   found
     */
    public IEditorDescriptor findEditor(String editorId);

    /**
     * Returns the default editor. The default editor always exist.
     *
     * @return the descriptor of the default editor
     * @deprecated The system external editor is the default editor.
     * Use <code>findEditor(IEditorRegistry.SYSTEM_EXTERNAL_EDITOR_ID)</code>
     * instead.
     */
    public IEditorDescriptor getDefaultEditor();

    /**
	 * Returns the default editor for a given file name. This method assumes an
	 * unknown content type for the given file.
	 * <p>
	 * The default editor is determined by taking the file extension for the
	 * file and obtaining the default editor for that extension.
	 * </p>
	 * 
	 * @param fileName
	 *            the file name in the system
	 * @return the descriptor of the default editor, or <code>null</code> if
	 *         not found
	 */
    public IEditorDescriptor getDefaultEditor(String fileName);
    
    /**
     * Returns the default editor for a given file name and with the given content type.  
     * <p>
     * The default editor is determined by taking the file extension for the
     * file and obtaining the default editor for that extension.
     * </p>
     *
     * @param fileName the file name in the system
     * @param contentType the content type or <code>null</code> for the unknown content type
     * @return the descriptor of the default editor, or <code>null</code> if not
     *   found
     */
    public IEditorDescriptor getDefaultEditor(String fileName, IContentType contentType);

    /**
	 * Returns the list of file editors registered to work against the file with
	 * the given file name. This method assumes an unknown content type for the
	 * given file.
	 * <p>
	 * Note: Use <code>getDefaultEditor(String)</code> if you only the need
	 * the default editor rather than all candidate editors.
	 * </p>
	 * 
	 * @param fileName
	 *            the file name in the system
	 * @return a list of editor descriptors
	 */
    public IEditorDescriptor[] getEditors(String fileName);
 
    /**
	 * Returns the list of file editors registered to work against the file with
	 * the given file name and with the given content type.
	 * <p>
	 * Note: Use <code>getDefaultEditor(String)</code> if you only the need
	 * the default editor rather than all candidate editors.
	 * </p>
	 * 
	 * @param fileName
	 *            the file name in the system
	 * @param contentType
	 *            the content type or <code>null</code> for the unknown
	 *            content type
	 * @return a list of editor descriptors
	 */
    public IEditorDescriptor[] getEditors(String fileName, IContentType contentType);

    /**
     * Returns a list of mappings from file type to editor.  The resulting list
     * is sorted in ascending order by file extension.
     * <p>
     * Each mapping defines an extension and the set of editors that are 
     * available for that type. The set of editors includes those registered 
     * via plug-ins and those explicitly associated with a type by the user 
     * in the workbench preference pages.
     * </p>
     *
     * @return a list of mappings sorted alphabetically by extension
     */
    public IFileEditorMapping[] getFileEditorMappings();

    /**
	 * Returns the image descriptor associated with a given file. This image is
	 * usually displayed next to the given file. This method assumes an unknown
	 * content type for the given file.
	 * <p>
	 * The image is determined by taking the file extension of the file and
	 * obtaining the image for the default editor associated with that
	 * extension. A default image is returned if no default editor is available.
	 * </p>
	 * 
	 * @param filename
	 *            the file name in the system
	 * @return the descriptor of the image to display next to the file
	 */
    public ImageDescriptor getImageDescriptor(String filename);
	
    /**
	 * Returns the image descriptor associated with a given file. This image is
	 * usually displayed next to the given file.
	 * <p>
	 * The image is determined by taking the file extension of the file and
	 * obtaining the image for the default editor associated with that
	 * extension. A default image is returned if no default editor is available.
	 * </p>
	 * 
	 * @param filename
	 *            the file name in the system
	 * @param contentType
	 *            the content type of the file or <code>null</code> for the
	 *            unknown content type
	 * @return the descriptor of the image to display next to the file
	 */
    public ImageDescriptor getImageDescriptor(String filename, IContentType contentType);

    /**
     * Removes the given property listener from this registry.
     * Has no effect if an identical listener is not registered.
     *
     * @param listener a property listener
     */
    public void removePropertyListener(IPropertyListener listener);

    /**
     * Sets the default editor id for the files that match that
     * specified file name or extension. The specified editor must be
     * defined as an editor for that file name or extension.
     *
     * @param fileNameOrExtension the file name or extension pattern (e.g. "*.xml");
     * @param editorId the editor id or <code>null</code> for no default
     */
    public void setDefaultEditor(String fileNameOrExtension, String editorId);

    /**
     * Returns whether there is an in-place editor that could handle a file
     * with the given name.
     * 
     * @param filename the file name
     * @return <code>true</code> if an in-place editor is available, and
     * <code>false</code> otherwise
     * @since 1.1
     */
    public boolean isSystemInPlaceEditorAvailable(String filename);

    /**
     * Returns whether the system has an editor that could handle a file
     * with the given name.
     * 
     * @param filename the file name
     * @return <code>true</code> if an external editor available, and
     * <code>false</code> otherwise
     * @since 1.5
     */
    public boolean isSystemExternalEditorAvailable(String filename);

    /**
     * Returns the image descriptor associated with the system editor that
     * would be used to edit this file externally.
     *
     * @param filename the file name
     * @return the descriptor of the external editor image, or <code>null</code>
     * if none
     * @since 1.5
     */
    public ImageDescriptor getSystemExternalEditorImageDescriptor(
            String filename);
}