/*******************************************************************************
* 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;
import java.util.List;
import org.eclipse.wst.sse.ui.internal.contentassist.CompletionProposalCategory;
/**
* <p>Implementers of the <code>org.eclipse.wst.sse.ui.completionProposalCategoriesConfiguration</code>
* extension can implement this interface if their configuration should be user edible and thus
* needs writing capabilities</p>
*
* <p><b>NOTE: </b>Implementers must have a 0 argument constructor so class can be instantiated by
* extension.</p>
*
* @see ICompletionProposalCategoriesConfigurationReader
*/
public interface ICompletionProposalCategoriesConfigurationWriter extends
ICompletionProposalCategoriesConfigurationReader {
/**
* <p>If a writer has a known associated properties page then that properties
* page ID can be used so that error messages during the content assist process
* can link to that preference page to allow the user to change the settings</p>
*
* @return <code>true</code> if this writer has a known associated properties
* preference page, <code>false</code> otherwise
*/
boolean hasAssociatedPropertiesPage();
/**
* @return If {@link #hasAssociatedPropertiesPage()} returns <code>true</code> then
* this method must return a valid properties page ID where the user can edit the
* content assist configuration, else it can return <code>null</code>
*/
String getPropertiesPageID();
/**
* <p>Sets whether or not the given category should be displayed on its own content
* assist page.<p>
*
* <p><b>NOTE: </b>This preference should <b>NOT</b> be saved permanently here, that action
* should wait until {@link #saveConfiguration()} is called</p>
*
* @param categoryID the category that should either be displayed on its own content
* assist page or not
* @param shouldDisplay <code>true</code> if the given category should be displayed
* on its own content assist page, <code>false</code> otherwise
*/
void setShouldDisplayOnDefaultPage(String categoryID, boolean shouldDisplay);
/**
* <p>Sets whether or not the given category should be displayed on the default content
* assist page.<p>
*
* <p><b>NOTE: </b>This preference should <b>NOT</b> be saved permanently here, that action
* should wait until {@link #saveConfiguration()} is called</p>
*
* @param categoryID the category that should either be displayed on the default content
* assist page or not
* @param shouldDisplay <code>true</code> if the given category should be displayed
* on the default content assist page, <code>false</code> otherwise
*/
void setShouldDisplayOnOwnPage(String categoryID, boolean shouldDisplay);
/**
* <p>Sets the order in which the categories should be cycled when invoking content
* assist multiple times. Event categories that are not activated to display on their
* own content assist page can be listed here so that when activated to display on their
* own page they have a rank. The entire order needs to be re-set each time one category
* moves because the writer has no way of knowing how to move just one category in the order</p>
*
* <p><b>NOTE: </b>This preference should <b>NOT</b> be saved permanently here, that action
* should wait until {@link #saveConfiguration()} is called</p>
*
* @param order <code>{@link List}<{@link String}></code>
* <ul><li><b>values:</b> {@link CompletionProposalCategory} IDs</li></ul>
*/
void setPageOrder(List order);
/**
* <p>Sets the order in which the categories should be listed on the default page.
* Event categories that are not activated to display on the default content assist
* page can be listed here so that when activated to display on the default page
* they have a rank. The entire order needs to be re-set each time one category
* moves because the writer has no way of knowing how to move just one category in the order</p>
*
* <p><b>NOTE: </b>This preference should <b>NOT</b> be saved permanently here, that action
* should wait until {@link #saveConfiguration()} is called</p>
*
* @param order <code>{@link List}<{@link String}></code>
* <ul><li><b>values:</b> {@link CompletionProposalCategory} IDs</li></ul>
*/
void setDefaultPageOrder(List order);
/**
* <p>Should load the default settings from wherever they are being stored</p>
*/
void loadDefaults();
/**
* <p>Should save the configuration permanently. Typically called after the user
* changes some preferences using a preference page and then applies them, but if they do
* not apply the changes then this function should not be called. This is the reason why the
* various <code>set*</code> methods should not permanently save the configuration</p>
*
* @return <code>true</code> if the save was successful, <code>false</code> otherwise
*/
boolean saveConfiguration();
}