1 package org.argeo.cms.ui.eclipse.forms.editor;
2 import org.argeo.cms.ui.eclipse.forms.IManagedForm;
3 import org.eclipse.swt.widgets.Control;
4 /**
5 * Interface that all GUI pages need to implement in order
6 * to be added to FormEditor part. The interface makes
7 * several assumptions:
8 * <ul>
9 * <li>The form page has a managed form</li>
10 * <li>The form page has a unique id</li>
11 * <li>The form page can be GUI but can also wrap a complete
12 * editor class (in that case, it should return <code>true</code>
13 * from <code>isEditor()</code> method).</li>
14 * <li>The form page is lazy i.e. understands that
15 * its part control will be created at the last possible
16 * moment.</li>.
17 * </ul>
18 * <p>Existing editors can be wrapped by implementing
19 * this interface. In this case, 'isEditor' should return <code>true</code>.
20 * A common editor to wrap in <code>TextEditor</code> that is
21 * often added to show the raw source code of the file open into
22 * the multi-page editor.
23 *
24 * @since 1.0
25 */
26 public interface IFormPage {
27 /**
28 * @param editor
29 * the form editor that this page belongs to
30 */
31 void initialize(FormEditor editor);
32 /**
33 * Returns the editor this page belongs to.
34 *
35 * @return the form editor
36 */
37 FormEditor getEditor();
38 /**
39 * Returns the managed form of this page, unless this is a source page.
40 *
41 * @return the managed form or <samp>null </samp> if this is a source page.
42 */
43 IManagedForm getManagedForm();
44 /**
45 * Indicates whether the page has become the active in the editor. Classes
46 * that implement this interface may use this method to commit the page (on
47 * <code>false</code>) or lazily create and/or populate the content on
48 * <code>true</code>.
49 *
50 * @param active
51 * <code>true</code> if page should be visible, <code>false</code>
52 * otherwise.
53 */
54 void setActive(boolean active);
55 /**
56 * Returns <samp>true </samp> if page is currently active, false if not.
57 *
58 * @return <samp>true </samp> for active page.
59 */
60 boolean isActive();
61 /**
62 * Tests if the content of the page is in a state that allows the
63 * editor to flip to another page. Typically, pages that contain
64 * raw source with syntax errors should not allow editors to
65 * leave them until errors are corrected.
66 * @return <code>true</code> if the editor can flip to another page,
67 * <code>false</code> otherwise.
68 */
69 boolean canLeaveThePage();
70 /**
71 * Returns the control associated with this page.
72 *
73 * @return the control of this page if created or <samp>null </samp> if the
74 * page has not been shown yet.
75 */
76 Control getPartControl();
77 /**
78 * Page must have a unique id that can be used to show it without knowing
79 * its relative position in the editor.
80 *
81 * @return the unique page identifier
82 */
83 String getId();
84 /**
85 * Returns the position of the page in the editor.
86 *
87 * @return the zero-based index of the page in the editor.
88 */
89 int getIndex();
90 /**
91 * Sets the position of the page in the editor.
92 *
93 * @param index
94 * the zero-based index of the page in the editor.
95 */
96 void setIndex(int index);
97 /**
98 * Tests whether this page wraps a complete editor that
99 * can be registered on its own, or represents a page
100 * that cannot exist outside the multi-page editor context.
101 *
102 * @return <samp>true </samp> if the page wraps an editor,
103 * <samp>false </samp> if this is a form page.
104 */
105 boolean isEditor();
106 /**
107 * A hint to bring the provided object into focus. If the object is in a
108 * tree or table control, select it. If it is shown on a scrollable page,
109 * ensure that it is visible. If the object is not presented in
110 * the page, <code>false</code> should be returned to allow another
111 * page to try.
112 *
113 * @param object
114 * object to select and reveal
115 * @return <code>true</code> if the request was successful, <code>false</code>
116 * otherwise.
117 */
118 boolean selectReveal(Object object);
119 }