/*******************************************************************************
* Copyright (c) 2003, 2005 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.application;
import org.eclipse.core.runtime.IAdaptable;
import org.eclipse.core.runtime.IStatus;
import org.eclipse.jface.resource.ImageDescriptor;
import org.eclipse.jface.window.WindowManager;
import org.eclipse.ui.IMemento;
import org.eclipse.ui.IWorkbench;
import org.eclipse.ui.IWorkbenchWindow;
import org.eclipse.ui.WorkbenchException;
/**
* Interface providing special access for configuring the workbench.
* <p>
* Note that these objects are only available to the main application
* (the plug-in that creates and owns the workbench).
* </p>
* <p>
* This interface is not intended to be implemented by clients.
* </p>
*
* @see WorkbenchAdvisor#initialize
* @since 3.0
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface IWorkbenchConfigurer {
/**
* Restore status code indicating that the saved state
* could not be restored, but that startup should continue
* with a reset state.
*
* @see #restoreState
*/
public static final int RESTORE_CODE_RESET = 1;
/**
* Restore status code indicating that the saved state
* could not be restored, and that the application
* must exit immediately without modifying any previously
* saved workbench state.
*/
public static final int RESTORE_CODE_EXIT = 2;
/**
* Returns the underlying workbench.
*
* @return the workbench
*/
public IWorkbench getWorkbench();
/**
* Returns whether the workbench state should be saved on close and
* restored on subsequent open.
* <p>
* The initial value is <code>false</code>.
* </p>
*
* @return <code>true</code> to save and restore workbench state, or
* <code>false</code> to forget current workbench state on close.
*/
public boolean getSaveAndRestore();
/**
* Sets whether the workbench state should be saved on close and
* restored on subsequent open.
*
* @param enabled <code>true</code> to save and restore workbench state, or
* <code>false</code> to forget current workbench state on close.
*/
public void setSaveAndRestore(boolean enabled);
/**
* Restores a workbench window from the given memento.
*
* @param memento the memento from which to restore the window's state
* @return the configurer for the restored window
* @throws WorkbenchException if an error occurred during the restore
* @see IWorkbenchWindowConfigurer#saveState(IMemento)
* @since 3.1
*/
public IWorkbenchWindowConfigurer restoreWorkbenchWindow(IMemento memento)
throws WorkbenchException;
/**
* Returns the workbench window manager.
*
* @return the workbench window manager
*
* Note:IWorkbenchWindow is implemented using JFace's Window (and therefore uses WindowManager),
* but this is an implementation detail
*/
public WindowManager getWorkbenchWindowManager();
/**
* Declares a workbench image.
* <p>
* The workbench remembers the given image descriptor under the given name,
* and makes the image available to plug-ins via
* {@link IWorkbench#getSharedImages() IWorkbench.getSharedImages()}.
* For "shared" images, the workbench remembers the image descriptor and
* will manages the image object create from it; clients retrieve "shared"
* images via
* {@link org.eclipse.ui.ISharedImages#getImage ISharedImages.getImage()}.
* For the other, "non-shared" images, the workbench remembers only the
* image descriptor; clients retrieve the image descriptor via
* {@link org.eclipse.ui.ISharedImages#getImageDescriptor
* ISharedImages.getImageDescriptor()} and are entirely
* responsible for managing the image objects they create from it.
* (This is made confusing by the historical fact that the API interface
* is called "ISharedImages".)
* </p>
*
* @param symbolicName the symbolic name of the image
* @param descriptor the image descriptor
* @param shared <code>true</code> if this is a shared image, and
* <code>false</code> if this is not a shared image
* @see org.eclipse.ui.ISharedImages#getImage
* @see org.eclipse.ui.ISharedImages#getImageDescriptor
*/
public void declareImage(String symbolicName, ImageDescriptor descriptor,
boolean shared);
/**
* Forces the workbench to close due to an emergency. This method should
* only be called when the workbench is in dire straights and cannot
* continue, and cannot even risk a normal workbench close (think "out of
* memory" or "unable to create shell"). When this method is called, an
* abbreviated workbench shutdown sequence is performed (less critical
* steps may be skipped). The workbench advisor is still called; however,
* it must not attempt to communicate with the user. While an emergency
* close is in progress, <code>emergencyClosing</code> returns
* <code>true</code>. Workbench advisor methods should always check this
* flag before communicating with the user.
*
* @see #emergencyClosing
*/
public void emergencyClose();
/**
* Returns whether the workbench is being closed due to an emergency.
* When this method returns <code>true</code>, the workbench is in dire
* straights and cannot continue. Indeed, things are so bad that we cannot
* even risk a normal workbench close. Workbench advisor methods should
* always check this flag before attempting to communicate with the user.
*
* @return <code>true</code> if the workbench is in the process of being
* closed under emergency conditions, and <code>false</code> otherwise
*/
public boolean emergencyClosing();
/**
* Returns an object that can be used to configure the given window.
*
* @param window a workbench window
* @return a workbench window configurer
*/
public IWorkbenchWindowConfigurer getWindowConfigurer(
IWorkbenchWindow window);
/**
* Returns the data associated with the workbench at the given key.
*
* @param key the key
* @return the data, or <code>null</code> if there is no data at the given
* key
*/
public Object getData(String key);
/**
* Sets the data associated with the workbench at the given key.
*
* @param key the key
* @param data the data, or <code>null</code> to delete existing data
*/
public void setData(String key, Object data);
/**
* Restores the workbench state saved from the previous session, if any.
* This includes any open windows and their open perspectives, open views
* and editors, layout information, and any customizations to the open
* perspectives.
* <p>
* This is typically called from the advisor's <code>openWindows()</code>
* method.
* </p>
*
* @return a status object indicating whether the restore was successful
* @see #RESTORE_CODE_RESET
* @see #RESTORE_CODE_EXIT
* @see WorkbenchAdvisor#openWindows
*/
public IStatus restoreState();
/**
* Opens the first time window, using the default perspective and
* default page input.
* <p>
* This is typically called from the advisor's <code>openWindows()</code>
* method.
* </p>
*
* @see WorkbenchAdvisor#openWindows
*/
public void openFirstTimeWindow();
/**
* Returns <code>true</code> if the workbench should exit when the last
* window is closed, <code>false</code> if the window should just be
* closed, leaving the workbench (and its event loop) running.
* <p>
* If <code>true</code>, the last window's state is saved before closing,
* so that it will be restored in the next session. This applies only if
* {@link #getSaveAndRestore() returns <code>true</code>}).
* </p>
* <p>
* If <code>false</code>, the window is simply closed, losing its state.
* </p>
* <p>
* If the workbench is left running, it can be closed using
* {@link IWorkbench#close()}, or a new window can be opened using
* {@link IWorkbench#openWorkbenchWindow(String, IAdaptable)}.
* </p>
* <p>
* The initial value is <code>true</code>.
* </p>
*
* @return <code>true</code> if the workbench will exit when the last
* window is closed, <code>false</code> if the window should just
* be closed
* @since 3.1
*/
public boolean getExitOnLastWindowClose();
/**
* Sets whether the workbench should exit when the last window is closed, or
* whether the window should just be closed, leaving the workbench (and its
* event loop) running.
* <p>
* For more details, see {@link #getExitOnLastWindowClose()}.
* </p>
*
* @param enabled
* <code>true</code> if the workbench should exit when the last
* window is closed, <code>false</code> if the window should
* just be closed
* @since 3.1
*/
public void setExitOnLastWindowClose(boolean enabled);
}