001: /*******************************************************************************
002: * Copyright (c) 2000, 2005 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.ui;
011:
012: import org.eclipse.core.runtime.IAdaptable;
013: import org.eclipse.jface.resource.ImageDescriptor;
014:
015: /**
016: * <code>IEditorInput</code> is a light weight descriptor of editor input,
017: * like a file name but more abstract. It is not a model. It is a description of
018: * the model source for an <code>IEditorPart</code>.
019: * <p>
020: * Clients implementing this editor input interface should override
021: * <code>Object.equals(Object)</code> to answer true for two inputs that are
022: * the same. The <code>IWorbenchPage.openEditor</code> APIs are dependent on
023: * this to find an editor with the same input.
024: * </p>
025: * <p>
026: * Clients should extend this interface to declare new types of editor inputs.
027: * </p>
028: * <p>
029: * An editor input is passed to an editor via the <code>IEditorPart.init</code>
030: * method. Due to the wide range of valid editor inputs, it is not possible to
031: * define generic methods for getting and setting bytes.
032: * </p>
033: * <p>
034: * Editor input must implement the <code>IAdaptable</code> interface;
035: * extensions are managed by the platform's adapter manager.
036: * </p>
037: * <p>
038: * Please note that it is important that the editor input be light weight.
039: * Within the workbench, the navigation history tends to hold on to editor
040: * inputs as a means of reconstructing the editor at a later time. The
041: * navigation history can hold on to quite a few inputs (i.e., the default is
042: * fifty). The actual data model should probably not be held in the input.
043: * </p>
044: *
045: *
046: * @see org.eclipse.ui.IEditorPart
047: * @see org.eclipse.ui.IWorkbenchPage#openEditor(IEditorInput, String)
048: * @see org.eclipse.ui.IWorkbenchPage#openEditor(IEditorInput, String, boolean)
049: */
050: public interface IEditorInput extends IAdaptable {
051: /**
052: * Returns whether the editor input exists.
053: * <p>
054: * This method is primarily used to determine if an editor input should
055: * appear in the "File Most Recently Used" menu. An editor input will appear
056: * in the list until the return value of <code>exists</code> becomes
057: * <code>false</code> or it drops off the bottom of the list.
058: *
059: * @return <code>true</code> if the editor input exists;
060: * <code>false</code> otherwise
061: */
062: public boolean exists();
063:
064: /**
065: * Returns the image descriptor for this input.
066: *
067: * <p>
068: * Note: although a null return value has never been permitted from this
069: * method, there are many known buggy implementations that return null.
070: * Clients that need the image for an editor are advised to use
071: * IWorkbenchPart.getImage() instead of IEditorInput.getImageDescriptor(),
072: * or to recover from a null return value in a manner that records the ID of
073: * the problematic editor input. Implementors that have been returning null
074: * from this method should pick some other default return value (such as
075: * ImageDescriptor.getMissingImageDescriptor()).
076: * </p>
077: *
078: * @return the image descriptor for this input; may be <code>null</code> if
079: * there is no image.
080: */
081: public ImageDescriptor getImageDescriptor();
082:
083: /**
084: * Returns the name of this editor input for display purposes.
085: * <p>
086: * For instance, when the input is from a file, the return value would
087: * ordinarily be just the file name.
088: *
089: * @return the name string; never <code>null</code>;
090: */
091: public String getName();
092:
093: /**
094: * Returns an object that can be used to save the state of this editor
095: * input.
096: *
097: * @return the persistable element, or <code>null</code> if this editor
098: * input cannot be persisted
099: */
100: public IPersistableElement getPersistable();
101:
102: /**
103: * Returns the tool tip text for this editor input. This text is used to
104: * differentiate between two input with the same name. For instance,
105: * MyClass.java in folder X and MyClass.java in folder Y. The format of the
106: * text varies between input types.
107: * </p>
108: *
109: * @return the tool tip text; never <code>null</code>.
110: */
111: public String getToolTipText();
112: }
|