org.argeo.cms.ui/src/org/argeo/cms/ui/eclipse/forms/editor/IFormPage.java

   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 }