/*******************************************************************************
 * Copyright (c) 2010 IBM Corporation and others. All rights reserved. This program and the
 * accompanying materials are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html Contributors: IBM Corporation - initial API and
 * implementation
 *******************************************************************************/
package org.eclipse.wst.sse.ui.preferences;

/**
 * <p>
 * Implementers of the <code>org.eclipse.wst.sse.ui.completionProposalCategoriesConfiguration</code>
 * extension will need an implementation of this interface for their extension
 * </p>
 * <p>
 * <b>NOTE: </b>Implementers must have a 0 argument constructor so class can be instantiated by
 * extension.
 * </p>
 * 
 * @see ICompletionProposalCategoriesConfigurationWriter
 */
public interface ICompletionProposalCategoriesConfigurationReader {
  /**
   * The default is to display a category on its own page if not otherwise defined by a property.
   */
  boolean DEFAULT_DISPLAY_ON_OWN_PAGE = true;

  /** The default is to display a category on the default content assist page. */
  boolean DEFAULT_INCLUDE_ON_DEFAULTS_PAGE = true;

  /** the default sort order if none is defined by a properties extension */
  int DEFAULT_SORT_ORDER = Integer.MAX_VALUE;

  /**
   * <p>
   * Determines if the given category should be displayed on its own content assist page
   * </p>
   * 
   * @param categoryID determine if this category should be displayed on its own content assist page
   * @return <code>true</code> if the given category should be displayed on its own content assist
   *         page, <code>false</code> otherwise
   */
  boolean shouldDisplayOnOwnPage(String categoryID);

  /**
   * <p>
   * Determines if the given category should be displayed on the default content assist page
   * </p>
   * 
   * @param categoryID determine if this category should be displayed on the default content assist
   *          page
   * @return <code>true</code> if the given category should be displayed on the default content
   *         assist page, <code>false</code> otherwise
   */
  boolean shouldDisplayOnDefaultPage(String categoryID);

  /**
   * <p>
   * Determines the sort order ranking of the given category when compared to the other categories,
   * this is used to determine the order in which the separate content assist pages should be
   * displayed
   * </p>
   * 
   * @param categoryID determine the sort order ranking of this category
   * @return the sort order ranking of the given category when compared to the other categories
   */
  int getPageSortOrder(String categoryID);

  /**
   * <p>
   * Determines the sort order ranking of the given category when compared to the other categories,
   * this is used to determine the order in which categories should be listed on the default page
   * </p>
   * 
   * @param categoryID determine the sort order ranking of this category
   * @return the sort order ranking of the given category when compared to the other categories
   */
  int getDefaultPageSortOrder(String categoryID);
}