package se.entra.phantom.server;

import java.util.Vector;

/**
 * The GofHostAreaIdentifier is an interface that must be implemented by all the classes that 
 * will be used to identify different areas on the host screen.
 * <p>
 * By splitting the host screen into different areas, it will be possible to use different rules for 
 * control identification for these areas, and in some areas only identify certain controls.
 * <p>
 * Examples of areas that might be identified are:
 * <ul>
 * <li>Title area</li>
 * <li>Function key area</li>
 * <li>Message area</li>
 * <li>Status area</li>
 * <li>Main area (the rest of the screen)</li>
 * </ul>
 * Each of the classes implementing this interface can load their own settings from the server.ini file.
 * <p>
 * The GofHostAreaIdentifier classes will also get a reference to all the controls created in their area, 
 * and will be able to implement their own layout rules.
 * <p>
 * The class implementing this interface must have a default constructor, without any parameters, since it 
 * will be created dynamically from the class name.
 */
public interface GofHostAreaIdentifier
{
  /**
   * Constant used to inform an area's layout method to layout the controls in a flow layout.
   */
  public static final int FLOW_LAYOUT = 1;

  /**
   * This method should get all the settings from the configuration file needed for this class.   
   * @param confFile   A reference to the IniFile instance that holds the current server configuration file's settings.
   * @param subsection The name of the subsection used for the current Gui-on-the-Fly settings.
   */
  public void getAreaSettings( IniFile confFile, String subsection );

  /**
   * This method must implement the code for identifying the area the class is supposed to identify. 
   * It should also store the GofHostFields that belong to this area.
   * @param gofHostFields A <code>Vector</code> containing all the GofHostFields in the part of the 
   *                      screen area to be analyzed.
   * @param x             The start column of the area to be analyzed.
   * @param y             The start line of the area to be analyzed.
   * @param w             The width of the area to be analyzed.
   * @param h             The height of the area to be analyzed.
   * @return The method must return a <code>Vector</code> with all unused GofHostFields, that is the 
   * GofHostFields from the first parameter, not belonging to this area.
   */
  public Vector<GofHostField> identifyArea( Vector<GofHostField> gofHostFields, int x, int y, int w, int h );

  /**
   * This method adds a new PhantomControl to this area. The method should store the control internally 
   * in the class. This makes it possible for this class to implement the laying out of the components.
   * @return This area's GofHostFields.
   */
  public Vector<GofHostField> getAreasGofHostFields( );

  /**
   * Adds a new PhantomControl to the area.
   * @param phantomControl The control to add to this area.
   */
  public void addControl( PhantomControl phantomControl );

  /**
   * This method should layout the controls belonging to this area according to the layout rule 
   * specified by the parameter.
   */
  public void layout( );
}