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