ICheatSheetViewer


1   /*******************************************************************************
2    * Copyright (c) 2004, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.ui.cheatsheets;
12  
13  import java.net.URL  ;
14  import java.util.Map  ;
15  
16  import org.eclipse.swt.widgets.Composite;
17  import org.eclipse.swt.widgets.Control;
18  
19  /**
20   * A cheat sheet viewer.
21   * <p>
22   * Clients call {@link CheatSheetViewerFactory#createCheatSheetView()} to create
23   * a cheat sheet viewer instance, and then call the viewer's 
24   * <code>createPartControl</code> method to have it create the viewer's control
25   * under the specified SWT composite. The viewer's control can then be retrieved
26   * using <code>getControl</code> to arrange layout. The <code>setInput</code>
27   * methods are used to set (or clear) the cheat sheet shown in the viewer,
28   * and can be called either before or after the viewer's controls have been
29   * created and laid out.
30   * </p>
31   * <p>
32   * The execution states of open cheat sheets are maintained and persisted
33   * globally using the cheat sheet id as the key.
34   * </p>
35   * <p>
36   * This interface is not intended to be implemented by clients.
37   * </p>
38   * 
39   * @see CheatSheetViewerFactory
40   * @since 3.0
41   */
42  public interface ICheatSheetViewer {
43  
44      /**
45       * Creates the SWT controls for this cheat sheet viewer.
46       * <p>
47       * When the parent Composite is disposed, this will automatically
48       * dispose the controls added by this viewer (and release any other 
49       * viewer-specific state).
50       * </p>
51       *
52       * @param parent the parent control
53       */
54      public void createPartControl(Composite parent);
55  
56      /**
57       * Returns the primary control associated with this viewer.
58       *
59       * @return the SWT control which displays this viewer's
60       * content, or <code>null</code> if this viewer's controls
61       * have not yet been created.
62       */
63      public Control getControl();
64  
65      /**
66       * Returns the id of the cheat sheet showing in this view.
67       * 
68       * @return id the cheat sheet id, or <code>null</code> if the
69       * view is not showing a cheat sheet
70       */
71      public String   getCheatSheetID();
72  
73      /**
74       * Asks this cheat sheet viewer to take focus.
75       */
76      public void setFocus();
77  
78      /**
79       * Sets the cheat sheet viewer to show the cheat sheet with 
80       * the given id. The cheat sheet content file is located via the
81       * <code>org.eclipse.ui.cheatsheets.cheatSheetContent</code>
82       * extension point. The viewer shows an error message if there
83       * is no cheat sheet with the given id.
84       * </p>
85       * <p>
86       * The execution states of open cheat sheets are maintained
87       * and persisted globally using the cheat sheet id as the key. 
88       * </p>
89       * 
90       * @param id the cheat sheet id, or <code>null</code> to show
91       * no cheat sheet in this viewer
92       */
93      public void setInput(String   id);
94  
95      /**
96       * Sets the cheat sheet viewer to show the cheat sheet with the 
97       * given cheat sheet content file. The viewer shows an error
98       * message if the cheat sheet content file cannot be opened or
99       * parsed.
100      * <p>
101      * The execution states of open cheat sheets are maintained
102      * and persisted globally using the cheat sheet id as the key. 
103      * This means that each cheat sheet must have a distinct id,
104      * including ones opened from URLs.
105      * </p>
106      * <p>
107      * Use the other <code>setInput</code> method to clear
108      * the viewer; that is, call <code>setInput(null)</code>.
109      * </p>
110      * 
111      * @param id the id to give this cheat sheet
112      * @param name the name to give this cheat sheet
113      * @param url URL of the cheat sheet content file
114      * @exception IllegalArgumentException if the parameters
115      * are <code>null</code>
116      */
117     public void setInput(String   id, String   name, URL   url);
118     
119     /**
120      * Sets the currently active cheat sheet to its initial state and
121      * initalizes the cheat sheet manager data.
122      * @param cheatSheetData A map whose keys and values are all of type
123      * <code>java.lang.String</code> or <code>null</code> to reset all data in 
124      * the cheat sheet manager. 
125      * @since 3.2
126      */
127     public void reset(Map   cheatSheetData);
128 }
129
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags