001: /*******************************************************************************
002: * Copyright (c) 2004, 2007 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.ui.intro;
011:
012: import org.eclipse.ui.IWorkbenchWindow;
013:
014: /**
015: * Manages the intro part that introduces the product to new users.
016: * The intro part is typically shown the first time a product is started up.
017: * <p>
018: * The initial behavior of the intro part is controlled by the application
019: * from via the {@link org.eclipse.ui.application.WorkbenchWindowAdvisor#openIntro()}
020: * method.
021: * </p>
022: * <p>
023: * See {@link org.eclipse.ui.intro.IIntroPart} for details on where intro parts
024: * come from.
025: * </p>
026: * <p>
027: * This interface is not intended to be extended or implemented by clients.
028: * </p>
029: *
030: * @see org.eclipse.ui.IWorkbench#getIntroManager()
031: * @since 3.0
032: */
033: public interface IIntroManager {
034:
035: /**
036: * Closes the given intro part.
037: *
038: * @param part the intro part
039: * @return <code>true</code> if the intro part was closed, and
040: * <code>false</code> otherwise. <code>false</code> is returned
041: * if part is <code>null</code> or it is not the intro part returned
042: * by {@link #getIntro()}.
043: */
044: public boolean closeIntro(IIntroPart part);
045:
046: /**
047: * Returns the intro part. Returns <code>null</code> if there is no intro
048: * part, if it has been previously closed via {@link #closeIntro(IIntroPart)}
049: * or if there is an intro part but {@link #showIntro(IWorkbenchWindow, boolean)}
050: * has not yet been called to create it.
051: *
052: * @return the intro part, or <code>null</code> if none is available
053: */
054: public IIntroPart getIntro();
055:
056: /**
057: * Return whether an intro is available. Note that this checks whether
058: * there is an applicable intro part that could be instantiated and shown
059: * to the user.
060: * Use {@link #getIntro()} to discover whether an intro part has already
061: * been created.
062: *
063: * @return <code>true</code> if there is an intro that could be shown, and
064: * <code>false</code> if there is no intro
065: */
066: public boolean hasIntro();
067:
068: /**
069: * Return the standby state of the given intro part.
070: *
071: * @param part the intro part
072: * @return <code>true</code> if the part in its partially
073: * visible standy mode, and <code>false</code> if in its fully visible state.
074: * <code>false</code> is returned if part is <code>null</code> or it is not
075: * the intro part returned by {@link #getIntro()}.
076: */
077: boolean isIntroStandby(IIntroPart part);
078:
079: /**
080: * Sets the standby state of the given intro part. Intro part usually should
081: * render themselves differently in the full and standby modes. In standby
082: * mode, the part should be partially visible to the user but otherwise
083: * allow them to work. In full mode, the part should be fully visible and
084: * be the center of the user's attention.
085: * <p>
086: * This method does nothing if the part is <code>null</code> or is not
087: * the intro part returned by {@link #getIntro()}.
088: * </p>
089: *
090: * @param part the intro part, or <code>null</code>
091: * @param standby <code>true</code> to put the part in its partially
092: * visible standy mode, and <code>false</code> to make it fully visible.
093: */
094: public void setIntroStandby(IIntroPart part, boolean standby);
095:
096: /**
097: * Shows the intro part in the given workbench window. If the intro part has
098: * not been created yet, one will be created. If the intro part is currently
099: * being shown in some workbench window, that other window is made active.
100: *
101: * @param preferredWindow the preferred workbench window, or
102: * <code>null</code> to indicate the currently active workbench window
103: * @param standby <code>true</code> to put the intro part in its partially
104: * visible standy mode, and <code>false</code> to make it fully visible
105: * @return the newly-created or existing intro part, or <code>null</code>
106: * if no intro part is available or if <code>preferredWindow</code> is
107: * <code>null</code> and there is no currently active workbench window
108: */
109: public IIntroPart showIntro(IWorkbenchWindow preferredWindow,
110: boolean standby);
111:
112: /**
113: * Returns <code>true</code> if there is an intro content detector and it
114: * reports that new intro content is available.
115: *
116: * @return <code>true</code> if new intro content is available
117: *
118: * @since 3.3
119: */
120: public boolean isNewContentAvailable();
121: }
|