/*******************************************************************************
 * Copyright (c) 2009, 2014 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
 *     Simon Scholz <simon.scholz@vogella.com> - Bug 450411
 ******************************************************************************/
package org.eclipse.e4.ui.workbench.modeling;

import java.util.Collection;
import org.eclipse.e4.ui.model.application.ui.advanced.MPerspective;
import org.eclipse.e4.ui.model.application.ui.advanced.MPlaceholder;
import org.eclipse.e4.ui.model.application.ui.basic.MPart;

/**
 * The part service provides clients with the functionalities of showing and hiding parts. Part
 * events can also be tracked via the part service.
 * <p>
 * It is expected that any methods that are exposed by this service that takes an <code>MPart</code>
 * as an argument be a part that is actually being managed by this service.
 * </p>
 *
 * @since 1.0
 * @noimplement This interface is not intended to be implemented by clients.
 */
public interface EPartService {

	/**
	 * Used to tag the currently active part in a presentation for subsequent
	 * activation on session startup
	 */
	public static final String ACTIVE_ON_CLOSE_TAG = "activeOnClose"; //$NON-NLS-1$

	/**
	 * Applicable states that a part can be in. This will be used in conjunction
	 * with {@link EPartService#showPart(String, PartState)}.
	 */
	public enum PartState {

		/**
		 * Part state that indicates the part should be made visible and
		 * activated.
		 */
		ACTIVATE,

		/**
		 * Part state that indicates the part should be made visible though it
		 * may not necessarily be granted focus. If the part will be displayed
		 * in the same stack as the currently active part, then this has the
		 * same effect as <code>ACTIVATE</code>.
		 */
		VISIBLE,

		/**
		 * Part state that indicates the part should be created but not
		 * necessarily made visible.
		 */
		CREATE
	}

	/**
	 * A tag on a part to indicate that it should be removed from the model when
	 * it is hidden.
	 *
	 * @see #hidePart(MPart)
	 */
	public static final String REMOVE_ON_HIDE_TAG = "removeOnHide"; //$NON-NLS-1$

	/**
	 * Adds the given listener for part lifecycle events. Has no effect if an
	 * identical listener has already been registered.
	 * <p>
	 * <b>Note:</b> Listeners should be removed when no longer necessary.
	 * </p>
	 *
	 * @param listener
	 *            the listener to attach
	 */
	public void addPartListener(IPartListener listener);

	/**
	 * Removes the given listener so that it will no longer be notified of part
	 * lifecycle events. Has no effect if an identical listener has not been
	 * registered.
	 *
	 * @param listener
	 *            the listener to remove
	 */
	public void removePartListener(IPartListener listener);

	/**
	 * Activates the given part. The part will be brought to top (if necessary)
	 * and granted focus.
	 *
	 * @param part
	 *            the part to activate, must not be <code>null</code>
	 */
	public void activate(MPart part);

	/**
	 * Activates the given part. The part will be brought to top (if necessary)
	 * and, if {@code requiresFocus} is true, then granted focus.
	 *
	 * @param part
	 *            the part to activate, must not be <code>null</code>
	 * @param requiresFocus
	 *            if true, then also cause the part to acquire focus
	 */
	public void activate(MPart part, boolean requiresFocus);

	/**
	 * Ask the service to assign activation to a valid part in the currently
	 * active presentation.
	 */
	public void requestActivation();

	/**
	 * Brings this part to the top so that it will become visible to the end
	 * user. This does not imply that the part will be granted focus.
	 *
	 * @param part
	 *            the part to bring to top
	 */
	public void bringToTop(MPart part);

	/**
	 * Finds and returns a part with the given id.
	 *
	 * @param id
	 *            the id of the part to search for, must not be
	 *            <code>null</code>
	 * @return the part with the specified id, or <code>null</code> if no such
	 *         part could be found
	 */
	public MPart findPart(String id);

	/**
	 * Returns a collection of all the parts that are being managed by this part
	 * service.
	 *
	 * @return a collection of parts that are being managed by this service,
	 *         never <code>null</code>
	 */
	public Collection<MPart> getParts();

	/**
	 * Returns the active part.
	 *
	 * @return an active part within the scope of this service, or
	 *         <code>null</code> if no part is currently active
	 */
	public MPart getActivePart();

	/**
	 * Returns whether the specified part is currently visible to the end user.
	 *
	 * @param part
	 *            the part to check
	 * @return <code>true</code> if the part is currently visible,
	 *         <code>false</code> otherwise
	 */
	public boolean isPartVisible(MPart part);

	/**
	 * Creates a new part of the given id.
	 *
	 * @param id
	 *            the identifier of the part, must not be <code>null</code>
	 * @return a new part of the given id, or <code>null</code> if no part
	 *         descriptors can be found that match the specified id
	 */
	public MPart createPart(String id);

	/**
	 * Creates a new placeholder for a part of the given id.
	 *
	 * @param id
	 *            the identifier of the part, must not be <code>null</code>
	 * @return a new part of the given id, or <code>null</code> if no part
	 *         descriptors can be found that match the specified id
	 */
	public MPlaceholder createSharedPart(String id);

	/**
	 * Creates a new placeholder for a part of the given id.
	 *
	 * @param id
	 *            the identifier of the part, must not be <code>null</code>
	 * @param force
	 *            <code>true</code> if a new part should be created,
	 *            <code>false</code> if the window should be queried for a
	 *            shared part first
	 * @return a new part of the given id, or <code>null</code> if no part
	 *         descriptors can be found that match the specified id
	 */
	public MPlaceholder createSharedPart(String id, boolean force);

	/**
	 * Shows a part with the identified by the given id. In the event that there
	 * are multiple parts with the specified id, the client is recommended to
	 * use {@link #getParts()} and iterate over the collection to find the
	 * interested part and invoke {@link #showPart(MPart, PartState)} on it. The
	 * behavior of this method is dictated by the supplied state.
	 * <ul>
	 * <li>If <code>ACTIVATE</code> is supplied, then the part is made visible
	 * and granted focus.</li>
	 * <li>If <code>VISIBLE</code> is supplied, then the part will be made
	 * visible and possibly be granted focus depending on where it is relative
	 * to the active part. If it is in the same stack as the currently active
	 * part, then it will be granted focus.</li>
	 * <li>If <code>CREATE</code> is supplied, then the part will be
	 * instantiated though its contents may not necessarily be visible to the
	 * end user. visible to the end user.</li>
	 * </ul>
	 * </p>
	 *
	 * @param id
	 *            the identifier of the part, must not be <code>null</code>
	 * @param partState
	 *            the desired state of the shown part to be in
	 * @return the shown part, or <code>null</code> if no parts or part
	 *         descriptors can be found that match the specified id
	 */
	public MPart showPart(String id, PartState partState);

	/**
	 * Shows the given part.
	 * <p>
	 * <ul>
	 * <li>If there cannot be multiple parts of this type and a part already
	 * exists, the already existing part will be shown and returned.</li>
	 * <li>If multiple parts of this type is allowed, then the provided part
	 * will be shown and returned</li>
	 * </ul>
	 * </p>
	 * <p>
	 * The behavior of this method is dictated by the supplied state.
	 * <ul>
	 * <li>If <code>ACTIVATE</code> is supplied, then the part is made visible
	 * and granted focus.</li>
	 * <li>If <code>VISIBLE</code> is supplied, then the part will be made
	 * visible and possibly be granted focus depending on where it is relative
	 * to the active part. If it is in the same stack as the currently active
	 * part, then it will be granted focus.</li>
	 * <li>If <code>CREATE</code> is supplied, then the part will be
	 * instantiated though its contents may not necessarily be visible to the
	 * end user. visible to the end user.</li>
	 * </ul>
	 * </p>
	 *
	 * @param part
	 *            the part to show
	 * @param partState
	 *            the desired state of the shown part to be in
	 * @return the shown part
	 */
	public MPart showPart(MPart part, PartState partState);

	/**
	 * Hides the given part. The part must be a part managed by this service.
	 * <p>
	 * If the part has been tagged with the {@link #REMOVE_ON_HIDE_TAG} tag, it
	 * will be removed from the model when the service hides it.
	 * </p>
	 * <p>
	 * To save the part before hiding, use {@link #savePart(MPart, boolean)}:
	 * </p>
	 *
	 * <pre>
	 * if (partService.savePart(part, true)) {
	 * 	partService.hidePart(part);
	 * }
	 * </pre>
	 *
	 * @param part
	 *            the part to hide
	 * @see #savePart(MPart, boolean)
	 */
	public void hidePart(MPart part);

	/**
	 * Hides the given part. The part must be a part managed by this service.
	 * <p>
	 * If <code>force</code> is <code>true</code> or the part has been tagged
	 * with the {@link #REMOVE_ON_HIDE_TAG} tag, it will be removed from the
	 * model when the service hides it.
	 * </p>
	 * <p>
	 * To save the part before hiding, use {@link #savePart(MPart, boolean)}:
	 * </p>
	 *
	 * <pre>
	 * if (partService.savePart(part, true)) {
	 * 	partService.hidePart(part);
	 * }
	 * </pre>
	 *
	 * @param part
	 *            the part to hide
	 * @param force
	 *            if the part should be removed from the model regardless of its
	 *            {@link #REMOVE_ON_HIDE_TAG} tag
	 * @see #savePart(MPart, boolean)
	 */
	public void hidePart(MPart part, boolean force);

	/**
	 * Returns a collection of all the dirty parts that are being managed by
	 * this service.
	 *
	 *
	 * @return a collection of dirty parts that are being managed by this
	 *         service, never <code>null</code>
	 */
	public Collection<MPart> getDirtyParts();

	/**
	 * Saves the contents of the part if it is dirty and returns whether the
	 * operation completed.
	 *
	 * @param part
	 *            the part to save
	 * @param confirm
	 *            <code>true</code> if the user should be prompted prior to
	 *            saving the changes, and <code>false</code> to save changes
	 *            without asking
	 * @return <code>true</code> if the operation completed successfully,
	 *         <code>false</code> if the user canceled the operation or if an
	 *         error occurred while saving the changes
	 * @see #hidePart(MPart, boolean)
	 */
	public boolean savePart(MPart part, boolean confirm);

	/**
	 * Saves the contents of all dirty parts and returns whether the operation
	 * completed.
	 *
	 * @param confirm
	 *            <code>true</code> if the user should be prompted prior to
	 *            saving the changes, and <code>false</code> to save changes
	 *            without asking
	 * @return <code>true</code> if the operation completed successfully,
	 *         <code>false</code> if the user canceled the operation or if an
	 *         error occurred while saving the changes
	 */
	public boolean saveAll(boolean confirm);

	/**
	 * Switch to the specified perspective. It will be selected and brought to
	 * top (if necessary). It may not necessarily be granted focus if there is
	 * another active window present.
	 *
	 * @param perspective
	 *            the perspective to switch to, must not be <code>null</code>
	 *            and it must be a perspective that's being managed by this
	 *            service
	 * @noreference This method is not intended to be referenced by clients.
	 */
	public void switchPerspective(MPerspective perspective);

	/**
	 * Indicates whether a part with a certain elementId is currently rendered
	 * in a certain perspective or not.
	 *
	 * @param elementId
	 *            the id of the part, which should be checked
	 * @param perspective
	 *            the perspective, which may contain the part with the given
	 *            elementId
	 * @return <code>true</code> if the part with the given elementId is
	 *         rendered in the given perspective and <code>false</code>
	 *         otherwise
	 * @since 1.3
	 */
	public boolean isPartOrPlaceholderInPerspective(String elementId, MPerspective perspective);
}