org.eclipse.ui.cheatsheets.ICheatSheetViewer Maven / Gradle / Ivy
/*******************************************************************************
* Copyright (c) 2004, 2015 IBM Corporation and others.
*
* This program and the accompanying materials
* are made available under the terms of the Eclipse Public License 2.0
* which accompanies this distribution, and is available at
* https://www.eclipse.org/legal/epl-2.0/
*
* SPDX-License-Identifier: EPL-2.0
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.ui.cheatsheets;
import java.net.URL;
import java.util.Map;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Control;
/**
* A cheat sheet viewer.
*
* Clients call {@link CheatSheetViewerFactory#createCheatSheetView()} to create
* a cheat sheet viewer instance, and then call the viewer's
* createPartControl method to have it create the viewer's control
* under the specified SWT composite. The viewer's control can then be retrieved
* using getControl to arrange layout. The setInput
* methods are used to set (or clear) the cheat sheet shown in the viewer,
* and can be called either before or after the viewer's controls have been
* created and laid out.
*
*
* The execution states of open cheat sheets are maintained and persisted
* globally using the cheat sheet id as the key.
*
*
* @see CheatSheetViewerFactory
* @since 3.0
* @noimplement This interface is not intended to be implemented by clients.
* @noextend This interface is not intended to be extended by clients.
*/
public interface ICheatSheetViewer {
/**
* Creates the SWT controls for this cheat sheet viewer.
*
* When the parent Composite is disposed, this will automatically
* dispose the controls added by this viewer (and release any other
* viewer-specific state).
*
*
* @param parent the parent control
*/
public void createPartControl(Composite parent);
/**
* Returns the primary control associated with this viewer.
*
* @return the SWT control which displays this viewer's
* content, or null if this viewer's controls
* have not yet been created.
*/
public Control getControl();
/**
* Returns the id of the cheat sheet showing in this view.
*
* @return id the cheat sheet id, or null if the
* view is not showing a cheat sheet
*/
public String getCheatSheetID();
/**
* Asks this cheat sheet viewer to take focus.
*/
public void setFocus();
/**
* Sets the cheat sheet viewer to show the cheat sheet with
* the given id. The cheat sheet content file is located via the
* org.eclipse.ui.cheatsheets.cheatSheetContent
* extension point. The viewer shows an error message if there
* is no cheat sheet with the given id.
*
* The execution states of open cheat sheets are maintained
* and persisted globally using the cheat sheet id as the key.
*
*
* @param id the cheat sheet id, or null to show
* no cheat sheet in this viewer
*/
public void setInput(String id);
/**
* Sets the cheat sheet viewer to show the cheat sheet with the
* given cheat sheet content file. The viewer shows an error
* message if the cheat sheet content file cannot be opened or
* parsed.
*
* The execution states of open cheat sheets are maintained
* and persisted globally using the cheat sheet id as the key.
* This means that each cheat sheet must have a distinct id,
* including ones opened from URLs.
*
*
* Use the other setInput method to clear
* the viewer; that is, call setInput(null).
*
*
* @param id the id to give this cheat sheet
* @param name the name to give this cheat sheet
* @param url URL of the cheat sheet content file
* @exception IllegalArgumentException if the parameters
* are null
*/
public void setInput(String id, String name, URL url);
/**
* Sets the currently active cheat sheet to its initial state and
* initalizes the cheat sheet manager data.
* @param cheatSheetData A map whose keys and values are all of type
* java.lang.String or null to reset all data in
* the cheat sheet manager.
* @since 3.2
*/
public void reset(Map cheatSheetData);
}