001: /*******************************************************************************
002: * Copyright (c) 2004, 2006 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.cheatsheets;
011:
012: import java.net.URL;
013: import java.util.Map;
014:
015: import org.eclipse.swt.widgets.Composite;
016: import org.eclipse.swt.widgets.Control;
017:
018: /**
019: * A cheat sheet viewer.
020: * <p>
021: * Clients call {@link CheatSheetViewerFactory#createCheatSheetView()} to create
022: * a cheat sheet viewer instance, and then call the viewer's
023: * <code>createPartControl</code> method to have it create the viewer's control
024: * under the specified SWT composite. The viewer's control can then be retrieved
025: * using <code>getControl</code> to arrange layout. The <code>setInput</code>
026: * methods are used to set (or clear) the cheat sheet shown in the viewer,
027: * and can be called either before or after the viewer's controls have been
028: * created and laid out.
029: * </p>
030: * <p>
031: * The execution states of open cheat sheets are maintained and persisted
032: * globally using the cheat sheet id as the key.
033: * </p>
034: * <p>
035: * This interface is not intended to be implemented by clients.
036: * </p>
037: *
038: * @see CheatSheetViewerFactory
039: * @since 3.0
040: */
041: public interface ICheatSheetViewer {
042:
043: /**
044: * Creates the SWT controls for this cheat sheet viewer.
045: * <p>
046: * When the parent Composite is disposed, this will automatically
047: * dispose the controls added by this viewer (and release any other
048: * viewer-specific state).
049: * </p>
050: *
051: * @param parent the parent control
052: */
053: public void createPartControl(Composite parent);
054:
055: /**
056: * Returns the primary control associated with this viewer.
057: *
058: * @return the SWT control which displays this viewer's
059: * content, or <code>null</code> if this viewer's controls
060: * have not yet been created.
061: */
062: public Control getControl();
063:
064: /**
065: * Returns the id of the cheat sheet showing in this view.
066: *
067: * @return id the cheat sheet id, or <code>null</code> if the
068: * view is not showing a cheat sheet
069: */
070: public String getCheatSheetID();
071:
072: /**
073: * Asks this cheat sheet viewer to take focus.
074: */
075: public void setFocus();
076:
077: /**
078: * Sets the cheat sheet viewer to show the cheat sheet with
079: * the given id. The cheat sheet content file is located via the
080: * <code>org.eclipse.ui.cheatsheets.cheatSheetContent</code>
081: * extension point. The viewer shows an error message if there
082: * is no cheat sheet with the given id.
083: * </p>
084: * <p>
085: * The execution states of open cheat sheets are maintained
086: * and persisted globally using the cheat sheet id as the key.
087: * </p>
088: *
089: * @param id the cheat sheet id, or <code>null</code> to show
090: * no cheat sheet in this viewer
091: */
092: public void setInput(String id);
093:
094: /**
095: * Sets the cheat sheet viewer to show the cheat sheet with the
096: * given cheat sheet content file. The viewer shows an error
097: * message if the cheat sheet content file cannot be opened or
098: * parsed.
099: * <p>
100: * The execution states of open cheat sheets are maintained
101: * and persisted globally using the cheat sheet id as the key.
102: * This means that each cheat sheet must have a distinct id,
103: * including ones opened from URLs.
104: * </p>
105: * <p>
106: * Use the other <code>setInput</code> method to clear
107: * the viewer; that is, call <code>setInput(null)</code>.
108: * </p>
109: *
110: * @param id the id to give this cheat sheet
111: * @param name the name to give this cheat sheet
112: * @param url URL of the cheat sheet content file
113: * @exception IllegalArgumentException if the parameters
114: * are <code>null</code>
115: */
116: public void setInput(String id, String name, URL url);
117:
118: /**
119: * Sets the currently active cheat sheet to its initial state and
120: * initalizes the cheat sheet manager data.
121: * @param cheatSheetData A map whose keys and values are all of type
122: * <code>java.lang.String</code> or <code>null</code> to reset all data in
123: * the cheat sheet manager.
124: * @since 3.2
125: */
126: public void reset(Map cheatSheetData);
127: }
|