/*
* Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies). 
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:
*
* Trace Builder interface
*
*/
package com.nokia.tracebuilder.engine;

import java.util.Iterator;

import com.nokia.tracebuilder.engine.source.SourceProperties;
import com.nokia.tracebuilder.model.TraceBuilderException;
import com.nokia.tracebuilder.model.TraceObject;

/**
 * Trace Builder interface
 * 
 */
public interface TraceBuilderInterface {

	/**
	 * Set the trace object as an active object. Can be called with null
	 * parameter to deselect the active object. Other functions of this
	 * interface will work with the selected trace object until this method or
	 * extensionSelected is called again.
	 * 
	 * @param object
	 *            the object selected from trace view
	 * @param syncView
	 *            if true, delegates the object to TraceBuilderView.selectObject
	 * @param sourceOpened
	 *            if true, trace from model is used, otherwise trace from selected object           
	 */
	public void traceObjectSelected(TraceObject object, boolean syncView, boolean sourceOpened);

	/**
	 * Selects an TraceLocation or TraceLocationList as the active object. The
	 * functions that expect the selected object to be a TraceObject will not
	 * work until traceObjectSelected is called again.
	 * 
	 * @param list
	 *            the selected location list
	 * @param location
	 *            the selected location from the list or null if only the list
	 *            was selected
	 * @param syncView
	 *            if true, delegates the location to
	 *            TraceBuilderView.selectLocation
	 */
	public void locationSelected(TraceLocationList list,
			TraceLocation location, boolean syncView);

	/**
	 * Creates a new trace.
	 * 
	 * @throws TraceBuilderException
	 *             if a trace cannot be created
	 */
	public void addTrace() throws TraceBuilderException;

	/**
	 * Creates a new trace based on unrelated location found from source.
	 * 
	 * @throws TraceBuilderException
	 *             if a trace cannot be created
	 */
	public void convertTrace() throws TraceBuilderException;

	/**
	 * Creates a new trace parameter and adds it to the currently active trace
	 * object.
	 * 
	 * @throws TraceBuilderException
	 *             if adding fails
	 */
	public void addParameter() throws TraceBuilderException;

	/**
	 * Creates a new constant value and adds it to the currently active constant
	 * table
	 * 
	 * @throws TraceBuilderException
	 *             if adding fails
	 */
	public void addConstant() throws TraceBuilderException;

	/**
	 * Select component to be used in case that one cpp file is included to more
	 * than one mmp file
	 * 
	 * @throws TraceBuilderException
	 *             if adding fails
	 */
	public void selectComponent()
			throws TraceBuilderException;

	/**
	 * Deletes the currently active trace object from the model.
	 * 
	 * @throws TraceBuilderException
	 *             if deleting fails
	 */
	public void delete() throws TraceBuilderException;

	/**
	 * Removes the currently active trace object or location from the source
	 * files
	 * 
	 * @throws TraceBuilderException
	 *             if removing fails
	 */
	public void removeFromSource() throws TraceBuilderException;

	/**
	 * Removes all unrelated trace locations from the source files
	 * 
	 * @throws TraceBuilderException
	 *             if removing fails
	 */
	public void removeUnrelatedFromSource() throws TraceBuilderException;

	/**
	 * Shows the properties of the active trace object.
	 * 
	 * @throws TraceBuilderException
	 *             if properties of active object cannot be shown
	 */
	public void showProperties() throws TraceBuilderException;

	/**
	 * Changes the focus between the view and source editor
	 */
	public void switchFocus();

	/**
	 * Opens the trace project related to given source file
	 * 
	 * @param modelName
	 *            the name for the model
	 * @throws TraceBuilderException
	 *             if startup fails
	 */
	public void openProject(String modelName)
			throws TraceBuilderException;

	/**
	 * Exports the trace project
	 * 
	 * @throws TraceBuilderException
	 *             if export fails
	 */
	public void exportProject() throws TraceBuilderException;

	/**
	 * Closes the trace project
	 */
	public void closeProject();

	/**
	 * Starts the code instrumenter
	 * 
	 * @throws TraceBuilderException
	 *             if startup fails
	 */
	public void startInstrumenter() throws TraceBuilderException;

	/**
	 * Shows a dialog, which can be used to select and delete traces
	 * 
	 * @throws TraceBuilderException
	 *             if deleting fails
	 */
	public void deleteMultipleTraces() throws TraceBuilderException;

	/**
	 * Creates a constant table from the source selection
	 * 
	 * @throws TraceBuilderException
	 *             if processing fails
	 */
	public void createConstantTableFromSelection() throws TraceBuilderException;
	
	/**
	 * Gets the open sources
	 * 
	 * @return the open sources
	 */
	public Iterator<SourceProperties> getOpenSources();
	
	/**
	 * Gets the current selection
	 * 
	 * @return the selection
	 */
	public TraceObject getSelectedObject();

}