org.argeo.cms.ui/src/org/argeo/cms/ui/eclipse/forms/IFormPart.java

   1 package org.argeo.cms.ui.eclipse.forms;
   2
   3 /**
   4  * Classes that implement this interface can be added to the managed form and
   5  * take part in the form life cycle. The part is initialized with the form and
   6  * will be asked to accept focus. The part can receive form input and can elect
   7  * to do something according to it (for example, select an object that matches
   8  * the input).
   9  * <p>
  10  * The form part has two 'out of sync' states in respect to the model(s) that
  11  * feed the form: <b>dirty</b> and <b>stale</b>. When a part is dirty, it
  12  * means that the user interacted with it and now its widgets contain state that
  13  * is newer than the model. In order to sync up with the model, 'commit' needs
  14  * to be called. In contrast, the model can change 'under' the form (as a result
  15  * of some actions outside the form), resulting in data in the model being
  16  * 'newer' than the content presented in the form. A 'stale' form part is
  17  * brought in sync with the model by calling 'refresh'. The part is responsible
  18  * for notifying the form when one of these states change in the part. The form
  19  * reserves the right to handle this notification in the most appropriate way
  20  * for the situation (for example, if the form is in a page of the multi-page
  21  * editor, it may do nothing for stale parts if the page is currently not
  22  * showing).
  23  * <p>
  24  * When the form is disposed, each registered part is disposed as well. Parts
  25  * are responsible for releasing any system resources they created and for
  26  * removing themselves as listeners from all event providers.
  27  *
  28  * @see IManagedForm
  29  * @since 1.0
  30  *
  31  */
  32 public interface IFormPart {
  33         /**
  34          * Initializes the part.
  35          *
  36          * @param form
  37          *            the managed form that manages the part
  38          */
  39         void initialize(IManagedForm form);
  40
  41         /**
  42          * Disposes the part allowing it to release allocated resources.
  43          */
  44         void dispose();
  45
  46         /**
  47          * Returns true if the part has been modified with respect to the data
  48          * loaded from the model.
  49          *
  50          * @return true if the part has been modified with respect to the data
  51          *         loaded from the model
  52          */
  53         boolean isDirty();
  54
  55         /**
  56          * If part is displaying information loaded from a model, this method
  57          * instructs it to commit the new (modified) data back into the model.
  58          *
  59          * @param onSave
  60          *            indicates if commit is called during 'save' operation or for
  61          *            some other reason (for example, if form is contained in a
  62          *            wizard or a multi-page editor and the user is about to leave
  63          *            the page).
  64          */
  65         void commit(boolean onSave);
  66
  67         /**
  68          * Notifies the part that an object has been set as overall form's input.
  69          * The part can elect to react by revealing or selecting the object, or do
  70          * nothing if not applicable.
  71          *
  72          * @return <code>true</code> if the part has selected and revealed the
  73          *         input object, <code>false</code> otherwise.
  74          */
  75         boolean setFormInput(Object input);
  76
  77         /**
  78          * Instructs form part to transfer focus to the widget that should has focus
  79          * in that part. The method can do nothing (if it has no widgets capable of
  80          * accepting focus).
  81          */
  82         void setFocus();
  83
  84         /**
  85          * Tests whether the form part is stale and needs refreshing. Parts can
  86          * receive notification from models that will make their content stale, but
  87          * may need to delay refreshing to improve performance (for example, there
  88          * is no need to immediately refresh a part on a form that is current on a
  89          * hidden page).
  90          * <p>
  91          * It is important to differentiate 'stale' and 'dirty' states. Part is
  92          * 'dirty' if user interacted with its editable widgets and changed the
  93          * values. In contrast, part is 'stale' when the data it presents in the
  94          * widgets has been changed in the model without direct user interaction.
  95          *
  96          * @return <code>true</code> if the part needs refreshing,
  97          *         <code>false</code> otherwise.
  98          */
  99         boolean isStale();
 100
 101         /**
 102          * Refreshes the part completely from the information freshly obtained from
 103          * the model. The method will not be called if the part is not stale.
 104          * Otherwise, the part is responsible for clearing the 'stale' flag after
 105          * refreshing itself.
 106          */
 107         void refresh();
 108 }