EditorCookie


1   /*
2    * The contents of this file are subject to the terms of the Common Development
3    * and Distribution License (the License). You may not use this file except in
4    * compliance with the License.
5    *
6    * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7    * or http://www.netbeans.org/cddl.txt.
8    *
9    * When distributing Covered Code, include this CDDL Header Notice in each file
10   * and include the License file at http://www.netbeans.org/cddl.txt.
11   * If applicable, add the following below the CDDL Header, with the fields
12   * enclosed by brackets [] replaced by your own identifying information:
13   * "Portions Copyrighted [year] [name of copyright owner]"
14   *
15   * The Original Software is NetBeans. The Initial Developer of the Original
16   * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17   * Microsystems, Inc. All Rights Reserved.
18   */
19  package org.openide.cookies;
20  
21  import org.openide.util.Task;
22  
23  import java.io.IOException  ;
24  
25  import javax.swing.text.StyledDocument  ;
26  
27  
28  /** Cookie defining standard operations with a text document and
29  * an editor that can display it.
30  * The cookie extends <code>LineCookie</code>
31  * because all implementations of editors should support access
32  * by lines.
33  * <P>
34  * The cookie provides interfaces for opening the file, closing the editor,
35  * background loading, saving of the document, and notification of modification.
36  * <P><STRONG>Warning:</STRONG> it is not guaranteed that the document
37  * returned from this cookie will persist for the full lifetime of the
38  * cookie. That is, if the editor window is closed and then reopened,
39  * it is possible for the document to change.
40  * The <CODE>{@link EditorCookie.Observable}</CODE> allows listening to
41  * changes of the state of the document. You should do this
42  * if you are listening to changes in the document itself, as otherwise
43  * you would get no notifications from a reopened document.
44  *
45  * @author Jaroslav Tulach
46  */
47  public interface EditorCookie extends LineCookie {
48      /** Instructs an editor to be opened. The operation can
49      * return immediately and the editor may be opened later.
50      * There can be more than one editor open, so one of them should be
51      * arbitrarily chosen and selected (typically given focus).
52      */
53      public void open();
54  
55      /** Closes all opened editors (if the user agrees) and
56      * flushes content of the document to file.
57      *
58      * @return <code>false</code> if the operation has been cancelled
59      */
60      public boolean close();
61  
62      /** Should load the document into memory. This is done
63      * in a different thread. A task for the thread is returned
64      * so other components can test whether the loading is finished or not.
65      * <p><em>Note</em> that this does not involve opening the actual Editor window.
66      * For that, use {@link #open}.
67      *
68      * @return task for control over the loading process
69      */
70      public Task prepareDocument();
71  
72      /** Get the document (and wait).
73       * See the {@link org.openide.text Editor API} for details on how this document should behave.
74      * <P>
75      * If the document is not yet loaded the method blocks until
76      * it is.
77      * <p><em>Note</em> that this does not involve opening the actual Editor window.
78      * For that, use {@link #open}.
79      *
80      * @return the styled document for this cookie
81      * @exception IOException if the document could not be loaded
82      */
83      public StyledDocument   openDocument() throws IOException  ;
84  
85      /** Get the document (but do not block).
86      * <p><em>Note</em> that this does not involve opening the actual Editor window.
87      * For that, use {@link #open}.
88      *
89      * @return the document, or <code>null</code> if it has not yet been loaded
90      */
91      public StyledDocument   getDocument();
92  
93      /** Save the document.
94       * This is done in the current thread.
95      * @exception IOException on I/O error
96      */
97      public void saveDocument() throws IOException  ;
98  
99      /** Test whether the document is modified.
100     * @return <code>true</code> if the document is in memory and is modified; <code>false</code> otherwise
101     */
102     public boolean isModified();
103 
104     /** Get a list of all editor panes opened on this object.
105     * The first item in the array should represent the component
106     * that is currently selected or that was most recently selected.
107     * (Typically, multiple panes will only be open as a result of cloning the editor component.)
108     *
109     * <p>The resulting panes are useful for a range of tasks;
110     * most commonly, getting the current cursor position or text selection,
111     * including the <code>Caret</code> object.
112     * <p>This method may also be used to test whether an object is already open
113     * in an editor, without actually opening it.
114     *
115     * @return an array of panes, or <code>null</code> if no pane is open from this file.
116     *   In no case is an empty array returned.
117     */
118     public javax.swing.JEditorPane  [] getOpenedPanes();
119 
120     /** The interface extends EditorCookie and allows observing changes
121      * in state of the text document.
122      *
123      * @since 3.40
124      */
125     interface Observable extends EditorCookie {
126         /** This property is fired when the result of {@link #getDocument}
127          * has changed. Typically it is after closing the editor.
128          */
129         public static final String   PROP_DOCUMENT = "document";
130 
131         /** This property is fired when modified state of the document
132          * has changed. See {@link #isModified}.
133          */
134         public static final String   PROP_MODIFIED = "modified";
135 
136         /** This property is fired when list of opened panes for the document
137          * has changed. See {@link #getOpenedPanes}.
138          */
139         public static final String   PROP_OPENED_PANES = "openedPanes";
140 
141         /** Add a PropertyChangeListener to the listener list.
142          * @param l  the PropertyChangeListener to be added
143          */
144         void addPropertyChangeListener(java.beans.PropertyChangeListener   l);
145 
146         /** Remove a PropertyChangeListener from the listener list.
147          * @param l the PropertyChangeListener to be removed
148          */
149         void removePropertyChangeListener(java.beans.PropertyChangeListener   l);
150     }
151 }
152
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags