01: /*******************************************************************************
02: * Copyright (c) 2004, 2006 IBM Corporation and others.
03: * All rights reserved. This program and the accompanying materials
04: * are made available under the terms of the Eclipse Public License v1.0
05: * which accompanies this distribution, and is available at
06: * http://www.eclipse.org/legal/epl-v10.html
07: *
08: * Contributors:
09: * IBM Corporation - initial API and implementation
10: *******************************************************************************/package org.eclipse.ui.cheatsheets;
11:
12: import java.util.Set;
13:
14: /**
15: * Manages the running of a cheat sheet.
16: * <p>
17: * Each cheat sheet that is opened in the UI is assigned its own cheat sheet
18: * manager, which stays with it until the cheat sheet is completed (or
19: * restarted). The cheat sheet manager is passed as a parameter to cheat
20: * sheet-aware actions which implement {@link ICheatSheetAction}. The manager
21: * carries arbitrary key-value data (strings) for the lifetime of a cheat sheet,
22: * and can be accessed via {@link #getData(String)}and
23: * {@link #setData(String, String)}. If the workbench is shut down while the
24: * cheat sheet is in progress, this data will generally be saved and later
25: * restored when the workbench is restarted and cheat sheet is resumed. The
26: * manager also supports a {@link CheatSheetListener}(specified via the
27: * "listener" attribute of the "cheatsheet" element in the cheat sheet content
28: * file), which is kept informed of life cycle events over the course of the
29: * cheat sheet's life time.
30: * </p>
31: * <p>
32: * This interface is not intended to be implemented by clients.
33: * </p>
34: *
35: * @since 3.0
36: */
37: public interface ICheatSheetManager {
38:
39: /**
40: * Returns the id of the cheat sheet managed by this manager.
41: *
42: * @return the cheat sheet id
43: */
44: public String getCheatSheetID();
45:
46: /**
47: * Returns the data value associated with the given key.
48: *
49: * @param key the key
50: * @return the string data associated with the key, or
51: * <code>null</code> none
52: * @exception IllegalArgumentException if <code>key</code>
53: * is <code>null</code>
54: */
55: public String getData(String key);
56:
57: /**
58: * Sets the data value associated with the given key.
59: * <p>
60: * Data associated with a cheat sheet manager is remembered
61: * for the life of the manager. All data is discarded when
62: * the cheat sheet is completed (or restarted).
63: * </p>
64: *
65: * @param key the key
66: * @param data the string data associated with the key,
67: * or <code>null</code> to remove
68: * @exception IllegalArgumentException if <code>key</code>
69: * is <code>null</code>
70: */
71: public void setData(String key, String data);
72:
73: /**
74: * Get the cheat sheet manager for the enclosing composite cheat sheet.
75: * @return The cheat sheet manager for the composite cheat sheet which contains
76: * this cheat sheet as a task or <code>null</code> if this cheatsheet was not
77: * opened as a subtask of a composite cheat sheet.
78: * @since 3.2
79: */
80: public ICheatSheetManager getParent();
81:
82: /**
83: * Get the keys for the data in this cheat sheet manager
84: * @return The set of keys.
85: * @since 3.2
86: */
87: public Set getKeySet();
88: }
|