path: root/org.eclipse.ui.intro/src/org/eclipse/ui/intro/config/CustomizableIntroPart.java

/*******************************************************************************
 * Copyright (c) 2004, 2016 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.ui.intro.config;

import org.eclipse.core.runtime.IAdapterFactory;
import org.eclipse.core.runtime.IRegistryChangeEvent;
import org.eclipse.core.runtime.IRegistryChangeListener;
import org.eclipse.core.runtime.PerformanceStats;
import org.eclipse.core.runtime.Platform;
import org.eclipse.swt.SWT;
import org.eclipse.swt.custom.StackLayout;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Control;
import org.eclipse.swt.widgets.Display;
import org.eclipse.ui.IMemento;
import org.eclipse.ui.IWorkbenchPreferenceConstants;
import org.eclipse.ui.PartInitException;
import org.eclipse.ui.PlatformUI;
import org.eclipse.ui.internal.intro.impl.IIntroConstants;
import org.eclipse.ui.internal.intro.impl.IntroPlugin;
import org.eclipse.ui.internal.intro.impl.Messages;
import org.eclipse.ui.internal.intro.impl.model.IntroModelRoot;
import org.eclipse.ui.internal.intro.impl.model.IntroPartPresentation;
import org.eclipse.ui.internal.intro.impl.model.loader.ContentProviderManager;
import org.eclipse.ui.internal.intro.impl.model.loader.ExtensionPointManager;
import org.eclipse.ui.internal.intro.impl.model.loader.ModelLoaderUtil;
import org.eclipse.ui.internal.intro.impl.parts.StandbyPart;
import org.eclipse.ui.internal.intro.impl.presentations.BrowserIntroPartImplementation;
import org.eclipse.ui.internal.intro.impl.util.DialogUtil;
import org.eclipse.ui.internal.intro.impl.util.Log;
import org.eclipse.ui.internal.intro.impl.util.ReopenUtil;
import org.eclipse.ui.intro.IIntroSite;
import org.eclipse.ui.part.IntroPart;

/**
 * A re-usable intro part that the Eclipse platform uses for its Out of the Box
 * Experience. It is a customizable intro part where both its presentation, and
 * its content can be customized based on a configuration. Both are contributed
 * using the org.eclipse.ui.intro.config extension point. There are two
 * presentations: an SWT browser based presentation, and a UI forms
 * presentation. Based on the configuration, one is chosen on startup. If a
 * Browser based presentation is selected, and the intro is being loaded on a
 * platform that does not support the SWT Browser control, the default behavior
 * is to degrade to UI forms presentation. Content displayed in this intro part
 * can be static or dynamic. Static is html files, dynamic is markup in content
 * files. Again, both of which can be specified using the above extension point.
 * <p>
 * Memento Support: This intro part tries to restore its previous state when
 * possible. The state of the intro page is remembered, along with which standby
 * content content part was opened. IStandbyContent parts are passed the Intro's
 * memento shortly after construction, and are expected to restore there own
 * state based on the memento. The customizable intro part handles there initial
 * creation on load, and leaves restoring state to content part. Same with
 * saving state. The memento is passed shortly before shutdown to enable storing
 * of part specific data.
 *
 * Note: This class was made public for re-use, as-is, as a valid class for the
 * <code>org.eclipse.ui.intro</code> extension point. It is not intended to be
 * subclassed or used otherwise.
 * </p>
 *
 * @since 3.0
 */

/*
 * Internal docs: This class wraps a presentation part and a standby part. The
 * standby part is only shown when an IntroURL asks to show standby or when we
 * are restarting an Intro with an old memento. An internal data object
 * "showStandbyPart" is set on the control by the intro URL to signal standby
 * part needed. This data is nulled when the close button on the standby part is
 * clicked, signaling that the standby part is no longer needed.
 */
public final class CustomizableIntroPart extends IntroPart implements
         IRegistryChangeListener {

    private IntroPartPresentation presentation;
    private StandbyPart standbyPart;
    private Composite container;
    private IMemento memento;
    IntroModelRoot model;
    // this flag is used to recreate a cached standby part. It is used once and
    // the set to false when the standby part is first created.
    private boolean restoreStandby;


    // Adapter factory to abstract out the StandbyPart implementation from APIs.
    IAdapterFactory factory = new IAdapterFactory() {

		@Override
		public Class<?>[] getAdapterList() {
            return new Class[] { StandbyPart.class, IntroPartPresentation.class };
        }

		@Override
		public <T> T getAdapter(Object adaptableObject, Class<T> adapterType) {
            if (!(adaptableObject instanceof CustomizableIntroPart))
                return null;

            if (adapterType.equals(StandbyPart.class)) {
				return adapterType.cast(getStandbyPart());
            } else if (adapterType.equals(IntroPartPresentation.class)) {
				return adapterType.cast(getPresentation());
            } else
                return null;
        }
    };

    public CustomizableIntroPart() {
        // register adapter to hide standbypart.
        Platform.getAdapterManager().registerAdapters(factory,
            CustomizableIntroPart.class);
        // model can not be loaded here because the configElement of this part
        // is still not loaded here.

        // if we are logging performance, start the UI creation start time.
        // Clock stops at the end of the standbyStateChanged event.
        if (Log.logPerformance) {
            if (PerformanceStats.ENABLED)
                PerformanceStats.getStats(
                    IIntroConstants.PERF_VIEW_CREATION_TIME,
                    IIntroConstants.INTRO).startRun();
            else
                // capture start time to be used when only Intro performance
                // trace
                // is turned on.
                IntroPlugin.getDefault().setUICreationStartTime(
                    System.currentTimeMillis());
        }
    }

    @Override
	public void init(IIntroSite site, IMemento memento)
            throws PartInitException {
        super.init(site, memento);
        IntroPlugin.getDefault().closeLaunchBar();
        // load the correct model based in the current Intro Part id. Set the
        // IntroPartId in the manager class.
        String introId = getConfigurationElement().getAttribute("id"); //$NON-NLS-1$
        ExtensionPointManager extensionPointManager = IntroPlugin.getDefault()
            .getExtensionPointManager();
        extensionPointManager.setIntroId(introId);
        model = extensionPointManager.getCurrentModel();

        if (model != null && model.hasValidConfig()) {

            boolean startAtHomePage = ReopenUtil.isReopenPreference();
			if (startAtHomePage) {
    			PlatformUI.getPreferenceStore().setValue(
    	        		IWorkbenchPreferenceConstants.SHOW_INTRO, true);
    			memento = null;
    		}
            // we have a valid config contribution, get presentation. Make sure
            // you pass correct memento.
            presentation = model.getPresentation();
            if (presentation != null)
                presentation.init(this, getMemento(memento,
                    IIntroConstants.MEMENTO_PRESENTATION_TAG));

            // standby part is not created here for performance.

            // cache memento, and detemine if we have a cached standby part.
            this.memento = memento;
            restoreStandby = needToRestoreStandby(memento);

            // add the registry listerner for dynamic awarness.
            Platform.getExtensionRegistry().addRegistryChangeListener(this,
                IIntroConstants.PLUGIN_ID);
        }

        if (model == null || !model.hasValidConfig())
            DialogUtil.displayErrorMessage(site.getShell(),
                Messages.CustomizableIntroPart_configNotFound,
                new Object[] { ModelLoaderUtil.getLogString(
                    getConfigurationElement(), null) }, null);

    }

    /**
     * Creates the UI based on how the InroPart has been configured.
     *
     * @see org.eclipse.ui.IWorkbenchPart#createPartControl(org.eclipse.swt.widgets.Composite)
     */
    @Override
	public void createPartControl(Composite parent) {
        container = new Composite(parent, SWT.NULL);
        StackLayout layout = new StackLayout();
        layout.marginHeight = 0;
        layout.marginWidth = 0;
        container.setLayout(layout);

        if (model != null && model.hasValidConfig()) {
            presentation.createPartControl(container);
            // do not create the standby part here for performance.
        }

        if (Log.logPerformance) {
            PerformanceStats stats = PerformanceStats.getStats(
                IIntroConstants.PERF_UI_ZOOM, IIntroConstants.INTRO);
            stats.startRun();
        }

    }




    /**
     * Determine if we need to recreate a standby part. Return true if we have a
     * standby part memento that is not for the empty part AND stangby memento
     * has been tagged for restore, ie: it was open when workbench closed.
     *
     * @param memento
     * @return <code>true</code> if we need to recreate a standby part
     */
    private boolean needToRestoreStandby(IMemento memento) {
        // If we have a standby memento, it means we closed with standby open,
        // and so recreate it.
        IMemento standbyMemento = getMemento(memento, IIntroConstants.MEMENTO_STANDBY_PART_TAG);
        if (standbyMemento == null)
            return false;
        String restore = standbyMemento.getString(IIntroConstants.MEMENTO_RESTORE_ATT);
        if (restore == null)
            return false;
        String cachedStandbyPart = standbyMemento
            .getString(IIntroConstants.MEMENTO_STANDBY_CONTENT_PART_ID_ATT);
        if (cachedStandbyPart != null
                && cachedStandbyPart.equals(IIntroConstants.EMPTY_STANDBY_CONTENT_PART))
            return false;

        return cachedStandbyPart != null ? true : false;
    }

    /*
     * Handled state changes. Recreates the standby part if workbench was shut
     * down with one.
     *
     * @see org.eclipse.ui.IIntroPart#standbyStateChanged(boolean)
     */
    @Override
	public void standbyStateChanged(boolean standby) {

        // do this only if there is a valid config.
        if (model == null || !model.hasValidConfig())
            return;

        if (!standby)
            // we started of not in standby, no need to restore standby.
            restoreStandby = false;

        boolean isStandbyPartNeeded = isStandbyPartNeeded();
        isStandbyPartNeeded = isStandbyPartNeeded | restoreStandby;

        try {
			if (standbyPart == null && standby && isStandbyPartNeeded)
			    // if standby part is not created yet, create it only if in
			    // standby, and we need to.
			    createStandbyPart();

			handleSetFocus(isStandbyPartNeeded);
			setTopControl(isStandbyPartNeeded ? getStandbyControl()
			        : getPresentationControl());
			// triger state change in presentation to enable/disable toobar
			// actions. For this, we need to disable actions as long as we are in
			// standby, or we need to show standby part.
			presentation.standbyStateChanged(standby, isStandbyPartNeeded);
		} catch (RuntimeException e) {
			Log.error("Exception thrown in intro", e); //$NON-NLS-1$
		}
    }

    /**
     * Returns true if we need to show the standby part. False in all other
     * cases. This basically overrides the workbench behavior of Standby/normal
     * states. The design here is that if the showStandbyPart flag is set, then
     * we always need to show the standby part.
     *
     * @return <code>true</code> if we need to show the standby part
     */
    private boolean isStandbyPartNeeded() {
        return container.getData(IIntroConstants.SHOW_STANDBY_PART) == null ? false : true;
    }

    /*
     * Create standby part. Called only when really needed. We reset the restore
     * falg, but we need to tag the intro part as needing standby.
     */
    private void createStandbyPart() {
        standbyPart = new StandbyPart(model);
        standbyPart.init(this, getMemento(memento, IIntroConstants.MEMENTO_STANDBY_PART_TAG));
        standbyPart.createPartControl((Composite) getControl());
        restoreStandby = false;
        container.setData(IIntroConstants.SHOW_STANDBY_PART, "true"); //$NON-NLS-1$
    }

    private void handleSetFocus(boolean standby) {
        if (standby) {
            // standby part is null when Intro has not gone into standby state
            // yet.
            if (standbyPart != null)
                standbyPart.setFocus();
        } else
            presentation.setFocus();
    }

    @Override
	public void setFocus() {
        handleSetFocus(IntroPlugin.isIntroStandby());
    }

    private void setTopControl(Control c) {
        // container has stack layout. safe to cast.
        StackLayout layout = (StackLayout) container.getLayout();
        layout.topControl = c;
        container.layout();
    }

    private Control getPresentationControl() {
        return container.getChildren()[0];
    }

    private Control getStandbyControl() {
        // the Container top control may have only one child if the standby
        // part is not created yet. This happens if the intro never goes into
        // standby. Doing this for performance.
        if (standbyPart != null)
            return container.getChildren()[1];
        return null;
    }

    IntroPartPresentation getPresentation() {
        return presentation;
    }

    @Override
	public void dispose() {
        super.dispose();
        // call dispose on both parts.
        if (presentation != null)
            presentation.dispose();
        if (standbyPart != null)
            standbyPart.dispose();
        // clear all loaded models since we are disposing of the Intro Part.
        IntroPlugin.getDefault().getExtensionPointManager().clear();
        ContentProviderManager.getInst().clear();
        // clean platform adapter.
        Platform.getAdapterManager().unregisterAdapters(factory,
            CustomizableIntroPart.class);
        if (model != null && model.hasValidConfig())
            Platform.getExtensionRegistry().removeRegistryChangeListener(this);

    }

    /**
     * @return Returns the standbyPart.
     */
    StandbyPart getStandbyPart() {
        return standbyPart;
    }

    /**
     * Returns the primary control associated with this Intro part.
     *
     * @return the SWT control which displays this Intro part's content, or
     *         <code>null</code> if this standby part's controls have not yet
     *         been created.
     */
    public Control getControl() {
        return container;
    }

    @Override
	public void saveState(IMemento memento) {
        // give presentation and standby part there own children to create a
        // name space for each. But save either the presentation or the standby
        // part as needing to be restored. This way if we close with a standby
        // mode, we dont get the cached standby part.

        // Find out if presentation or standby is at the top and restore
        // them. Container has stack layout. safe to cast.
        boolean restorePresentation = false;
        StackLayout layout = (StackLayout) container.getLayout();
        if (getPresentationControl().equals(layout.topControl))
            restorePresentation = true;

        IMemento presentationMemento = memento
            .createChild(IIntroConstants.MEMENTO_PRESENTATION_TAG);
        IMemento standbyPartMemento = memento
            .createChild(IIntroConstants.MEMENTO_STANDBY_PART_TAG);
        if (restorePresentation)
            presentationMemento.putString(IIntroConstants.MEMENTO_RESTORE_ATT, "true"); //$NON-NLS-1$
        else
            standbyPartMemento.putString(IIntroConstants.MEMENTO_RESTORE_ATT, "true"); //$NON-NLS-1$
        if (presentation != null)
            presentation.saveState(presentationMemento);
        if (standbyPart != null)
            standbyPart.saveState(standbyPartMemento);
    }

    private IMemento getMemento(IMemento memento, String key) {
        if (memento == null)
            return null;
        return memento.getChild(key);
    }

    /**
     * Support dynamic awarness.
     *
     * @see org.eclipse.core.runtime.IRegistryChangeListener#registryChanged(org.eclipse.core.runtime.IRegistryChangeEvent)
     */
    @Override
	public void registryChanged(final IRegistryChangeEvent event) {
        // Clear cached models first, then update UI by delegating to
        // implementation. wrap in synchExec because notification is
        // asynchronous. The design here is that the notification is centralized
        // here, then this event propagates and each receiving class reacts
        // accordingly.
        Display.getDefault().syncExec(() -> {
		    String currentPageId = model.getCurrentPageId();
		    // clear model, including content providers.
		    ExtensionPointManager.getInst().clear();
		    ContentProviderManager.getInst().clear();
		    // refresh to new model.
		    model = ExtensionPointManager.getInst().getCurrentModel();
		    // reuse existing presentation, since we just nulled it.
		    model.setPresentation(getPresentation());
		    // keep same page on refresh. No need for notification here.
		    model.setCurrentPageId(currentPageId, false);
		    if (getPresentation() != null)
		        getPresentation().registryChanged(event);

		});

    }

    /*
     * Internal test hook (Non-API).
     */
    public boolean internal_isFinishedLoading() {
    	BrowserIntroPartImplementation impl = (BrowserIntroPartImplementation)presentation.getIntroPartImplementation();
    	return impl.isFinishedLoading();
    }
}