1
2
3
4
5
6
7
8
9
10
11
12 package sk.uniba.euromath.editor;
13 import java.util.List;
14 import java.util.Set;
15 import javax.xml.transform.Source;
16 import org.eclipse.swt.widgets.Composite;
17 import sk.baka.ikslibs.ObjectSource;
18 import sk.baka.ikslibs.modify.DOMChangeCollector;
19 import sk.baka.ikslibs.modify.IChangeCollector;
20 import sk.uniba.euromath.document.XMLAccess;
21 import sk.uniba.euromath.editor.actions.IActionContributor;
22 import sk.uniba.euromath.editor.selections.IDOMSelectionChangedListener;
23 /***
24 * <p>
25 * Interface that each EuroMath2 editor must implement. Editor is a MVC
26 * controller, that uses renderer output (the view) to edit source document. One
27 * instance of editor edits one nameroot. Each editor receives its own instance
28 * of {@link IRenderer}. Editor is always associated with exactly one target
29 * namespace.
30 * </p>
31 * <p>
32 * The method call order is as follows: first the
33 * {@link #init(Source,IRenderer,Composite,XMLAccess,EditorSite)} method is
34 * called to initialize the editor. * After the initialization the editor must
35 * be able to display renderer's IFigures, process keyboard and mouse events.
36 * {@link #reinit(Source, IChangeCollector)} may be called at any time to inform
37 * renderer of partial data change.
38 * </p>
39 * <p>
40 * Editor can support only two kinds of sources: the
41 * {@link javax.xml.transform.dom.DOMSource DOMSource} and
42 * {@link ObjectSource ObjectSource}, because they can be easily accessed
43 * multiple times.
44 * </p>
45 * <p>
46 * Instance of editor is always used by a single thread - it should not be
47 * synchronized, resulting in faster execution.
48 * </p>
49 * @see sk.uniba.euromath.editor.IRenderer
50 * @see sk.uniba.euromath.editor.EditInstanceProvider
51 * @author Tomas Studva, Martin Vysny
52 */
53 public interface IEditor extends IDOMSelectionChangedListener {
54 /***
55 * <p>
56 * Initializes the editor. The editor should retrieve all figures from the
57 * renderer and display them on given composite. It must NOT resize nor move
58 * the composite or its children - this is handled by the EditorSite itself.
59 * </p>
60 * <p>
61 * The editor works with two 'kinds' of document:
62 * </p>
63 * <ul>
64 * <li>It displays the transformed document - the output of GENE framework.
65 * This document is contained in the <code>source</code> parameter, and it
66 * MUST NOT be modified. This document is given to the renderer instance.</li>
67 * <li>It modifies the source document, using the <code>xmlAccess</code>
68 * facility.</li>
69 * </ul>
70 * @param transformedDoc the transformed document, rendered by the renderer.
71 * May be instance of <code>DOMSource</code> or <code>ObjectSource</code>
72 * only. Editor is encouraged to throw any exception including
73 * <code>ClassCastException</code> if it encounters illegal objects, to
74 * detect invalid objects quickly and cleanly.
75 * @param renderer instance of the renderer, rendering the transformed
76 * document. The renderer instance is used only in this instance of editor.
77 * @param parent <code>Composite</code> where to install
78 * <code>IFigure</code>s.
79 * @param xmlAccess the source document accessor.
80 * @param editorSite host for this class.
81 * @throws EditorException if the editor cannot be initialized. In such case
82 * the common text editor/generic editor/read-only editor shall be used.
83 */
84 public void init(Source transformedDoc, IRenderer renderer,
85 Composite parent, XMLAccess xmlAccess, EditorSite editorSite)
86 throws EditorException;
87 /***
88 * <p>
89 * Reinitialize the editor when a partial change of the transformed document
90 * occurs. The reinitialization of renderer is already finished - editor
91 * should query for new figures for each changed element.
92 * </p>
93 * @param transformedDoc source with all changes already applied.
94 * @param changes defines changed elements. Has appropriate type for
95 * <code>transformedDoc</code> parameter, i.e. {@link DOMChangeCollector}
96 * for {@link javax.xml.transform.dom.DOMSource} etc.
97 */
98 public void reinit(Source transformedDoc, IChangeCollector changes);
99 /***
100 * Returns Composite where clients - children IEditors will(should) be
101 * created.
102 * @return composite for children editors placement
103 */
104 public Composite getClientComposite();
105 /***
106 * Returns composite which host this editor - composite received in init.
107 * @return composite where this editor is placed
108 */
109 public Composite getHostingComposite();
110 /***
111 * Returns IRenderer for this IEditor from init.
112 * @return renderer associated with this editor
113 */
114 public IRenderer getRenderer();
115 /***
116 * Ask this editor to set focus.
117 */
118 public void setFocus();
119 /***
120 * Prepares for end of work. Must remove this as listeners, ... .
121 */
122 public void dispose();
123 /***
124 * Paints all figures needed to repaint.
125 */
126 public void performPaintUpdate();
127 /***
128 * Returns action contributor, which can make bars special for this IEditor.
129 * @return action contributor to bars and menus
130 */
131 public IActionContributor getActionContributor();
132 /***
133 * Adds listener for focus events.
134 * @param listener
135 */
136 public void addFocusListener(IFocusListener listener);
137 /***
138 * Removes listener for focus events.
139 * @param listener
140 */
141 public void removeFocusListener(IFocusListener listener);
142 /***
143 * Returns ids of nodes which are graphically rendered(represented) by this
144 * editor. Id's are without :N suffix.
145 * @return new instance, list of ids which are visualized
146 */
147 public Set<String> getVisualizedIds();
148 /***
149 * Sorts ids in manner as they are graphicaly displayed. X and also Y
150 * coordinates of graphics for id is considered. Use full ids, include with
151 * their :N component.
152 * @param ids list of ids to sort
153 */
154 public void sortIds(List<String> ids);
155 }