package sale;

import sale.events.*;

/**
  * An abstract display that can display Form- and MenuSheets.
  *
  * <p>Displays are used to hide concrete user interface implementation details from the application
  * developer. Together with {@link FormSheet FormSheets} and {@link MenuSheet MenuSheets}
  * they provide a complete abstraction from concrete user interfaces. Whatever the concrete user
  * interface looks like, Displays, Form- and MenuSheets will always be handled in the same way by the
  * application.</p>
  *
  * <p>At any given point of time there may be up to one FormSheet and up to one MenuSheet set on a
  * given Display. The Display interface offers methods to set and close these Form- and MenuSheets.
  * as well as a restricted set of events that can be used to keep up to date with the current
  * state of the display.</p>
  *
  * @author Steffen Zschaler
  * @version 2.0 27/05/1999
  * @since v2.0
  */
public interface Display {

  /**
    * Set and display a FormSheet.
    *
    * <p>This method should attach a FormSheetContainer as the FormSheet's display,
    * get the FormSheet's caption, component and button bar and render them. The entire
    * peer creation should be synchronized using {@link FormSheet#getComponentLock}
    * and {@link FormSheet#getButtonsLock}, so as not to loose any events.</p>
    *
    * <p>If {@link FormSheet#waitResponse fs.waitResponse()} returns true,
    * <code>setFormSheet()</code> should block, until the FormSheet is closed by a matching
    * call to a <code>closeFormSheet()</code> method.</p>
    *
    * <p>If a FormSheet is already being displayed, <code>setFormSheet()</code> should cancel this
    * FormSheet prior to setting the new FormSheet.</p>
    *
    * @override Always
    *
    * @param fs the FormSheet to be displayed.
    *
    * @exception InterruptedException if an interrupt occured while waiting for the
    * FormSheet to be closed.
    */
  public void setFormSheet (FormSheet fs)
    throws InterruptedException;

  /**
    * Close the current FormSheet. It is up to the display whether the FormSheet will be cancelled or
    * just closed normally.
    *
    * @override Always
    */
  public void closeFormSheet();

  /**
    * Show a FormSheet, but do not close the current FormSheet. This method will
    * normally pop up an extra {@link JDisplayDialog} that has the FormSheet set.
    *
    * <p>This method should attach a FormSheetContainer as the FormSheet's display,
    * get the FormSheet's caption, component and button bar and render them. The entire
    * peer creation should be synchronized using {@link FormSheet#getComponentLock}
    * and {@link FormSheet#getButtonsLock}, so as not to loose any events.</p>
    *
    * <p>If {@link FormSheet#waitResponse fs.waitResponse()} returns true,
    * <code>popUpFormSheet()</code> should block, until the FormSheet is closed by a matching
    * call to a <code>closeFormSheet()</code> method.</p>
    *
    * <p>If a FormSheet is already being displayed, <code>popUpFormSheet()</code> must not close this
    * FormSheet prior to setting the new FormSheet.</p>
    *
    * @override Always
    *
    * @param fs the FormSheet to be displayed.
    *
    * @exception InterruptedException if an interrupt occured while waiting for the
    * FormSheet to be closed.
    */
  public void popUpFormSheet (FormSheet fs)
    throws InterruptedException;

  /**
    * Set and display a MenuSheet.
    *
    * <p>If a MenuSheet is already being displayed, <code>setMenuSheet()</code> should remove this
    * MenuSheet prior to setting the new MenuSheet.</p>
    *
    * @override Always
    *
    * @param ms the MenuSheet to be displayed. <code>null</code> is a valid value and should result in the
    * current MenuSheet being closed.
    */
  public void setMenuSheet (MenuSheet ms);

  /**
    * Return true to indicate that this is a display that can be used normally. The only subclass that
    * is actually allowed to return false is {@link NullDisplay}.
    *
    * @override Always
    */
  public boolean isUseableDisplay();

  /**
    * Register a FormSheetListener to be informed when a FormSheet is set or closed.
    *
    * @override Always
    *
    * @param fsl the FormSheetListener to be registered.
    */
  public void addFormSheetListener (FormSheetListener fsl);

  /**
    * Unregister a FormSheetListener to be informed when a FormSheet is set or closed.
    *
    * @override Always
    *
    * @param fsl the FormSheetListener to be unregistered.
    */
  public void removeFormSheetListener (FormSheetListener fsl);
}