1 /******************************************************************************* 2 * Copyright (c) 2000, 2015 IBM Corporation and others. 3 * 4 * This program and the accompanying materials 5 * are made available under the terms of the Eclipse Public License 2.0 6 * which accompanies this distribution, and is available at 7 * https://www.eclipse.org/legal/epl-2.0/ 8 * 9 * SPDX-License-Identifier: EPL-2.0 10 * 11 * Contributors: 12 * IBM Corporation - initial API and implementation 13 *******************************************************************************/ 14 package org.eclipse.ui; 15 16 import org.eclipse.core.runtime.IAdaptable; 17 import org.eclipse.jface.resource.ImageDescriptor; 18 19 /** 20 * <code>IEditorInput</code> is a light weight descriptor of editor input, like 21 * a file name but more abstract. It is not a model. It is a description of the 22 * model source for an <code>IEditorPart</code>. 23 * <p> 24 * Clients implementing this editor input interface should override 25 * <code>Object.equals(Object)</code> to answer true for two inputs that are the 26 * same. The <code>IWorkbenchPage.openEditor</code> APIs are dependent on this 27 * to find an editor with the same input. 28 * </p> 29 * <p> 30 * Clients should extend this interface to declare new types of editor inputs. 31 * </p> 32 * <p> 33 * An editor input is passed to an editor via the <code>IEditorPart.init</code> 34 * method. Due to the wide range of valid editor inputs, it is not possible to 35 * define generic methods for getting and setting bytes. 36 * </p> 37 * <p> 38 * Editor input must implement the <code>IAdaptable</code> interface; extensions 39 * are managed by the platform's adapter manager. 40 * </p> 41 * <p> 42 * Please note that it is important that the editor input be light weight. 43 * Within the workbench, the navigation history tends to hold on to editor 44 * inputs as a means of reconstructing the editor at a later time. The 45 * navigation history can hold on to quite a few inputs (i.e., the default is 46 * fifty). The actual data model should probably not be held in the input. 47 * </p> 48 * 49 * 50 * @see org.eclipse.ui.IEditorPart 51 * @see org.eclipse.ui.IWorkbenchPage#openEditor(IEditorInput, String) 52 * @see org.eclipse.ui.IWorkbenchPage#openEditor(IEditorInput, String, boolean) 53 */ 54 public interface IEditorInput extends IAdaptable { 55 /** 56 * Returns whether the editor input exists. 57 * <p> 58 * This method is primarily used to determine if an editor input should appear 59 * in the "File Most Recently Used" menu. An editor input will appear in the 60 * list until the return value of <code>exists</code> becomes <code>false</code> 61 * or it drops off the bottom of the list. 62 * 63 * @return <code>true</code> if the editor input exists; <code>false</code> 64 * otherwise 65 */ exists()66 boolean exists(); 67 68 /** 69 * Returns the image descriptor for this input. 70 * 71 * <p> 72 * Note: although a null return value has never been permitted from this method, 73 * there are many known buggy implementations that return null. Clients that 74 * need the image for an editor are advised to use IWorkbenchPart.getImage() 75 * instead of IEditorInput.getImageDescriptor(), or to recover from a null 76 * return value in a manner that records the ID of the problematic editor input. 77 * Implementors that have been returning null from this method should pick some 78 * other default return value (such as 79 * ImageDescriptor.getMissingImageDescriptor()). 80 * </p> 81 * 82 * @return the image descriptor for this input; may be <code>null</code> if 83 * there is no image. 84 */ getImageDescriptor()85 ImageDescriptor getImageDescriptor(); 86 87 /** 88 * Returns the name of this editor input for display purposes. 89 * <p> 90 * For instance, when the input is from a file, the return value would 91 * ordinarily be just the file name. 92 * 93 * @return the name string; never <code>null</code>; 94 */ getName()95 String getName(); 96 97 /** 98 * Returns an object that can be used to save the state of this editor input. 99 * 100 * @return the persistable element, or <code>null</code> if this editor input 101 * cannot be persisted 102 */ getPersistable()103 IPersistableElement getPersistable(); 104 105 /** 106 * Returns the tool tip text for this editor input. This text is used to 107 * differentiate between two input with the same name. For instance, 108 * MyClass.java in folder X and MyClass.java in folder Y. The format of the text 109 * varies between input types. 110 * 111 * @return the tool tip text; never <code>null</code>. 112 */ getToolTipText()113 String getToolTipText(); 114 } 115