From 19fc558bd1cfa91d1191b42ad30a6722bf182867 Mon Sep 17 00:00:00 2001 From: Jonathan Williams Date: Mon, 14 Mar 2016 16:51:23 -0400 Subject: [PATCH] Bug 488959 - API and extension point documentation Change-Id: Ie7ce292ab14d11f06f3e4eb2f719704ddb2dae0c Signed-off-by: Jonathan Williams --- .../schema/consoleToolbar.exsd | 42 +++++++--- .../remote/console/actions/ConsoleAction.java | 78 +++++++++++++++++-- .../actions/IConsoleActionFactory.java | 11 +++ 3 files changed, 112 insertions(+), 19 deletions(-) diff --git a/bundles/org.eclipse.remote.console/schema/consoleToolbar.exsd b/bundles/org.eclipse.remote.console/schema/consoleToolbar.exsd index 0b1adee0416..3454e830349 100644 --- a/bundles/org.eclipse.remote.console/schema/consoleToolbar.exsd +++ b/bundles/org.eclipse.remote.console/schema/consoleToolbar.exsd @@ -6,7 +6,7 @@ - [Enter description of this extension point.] + This extension point allows contributions to the TerminalConsole for various types of connections. It associates an action id with a connection type and factory. @@ -76,21 +76,20 @@ - - - - - - [Enter the first release in which this extension point appears.] - - - [Enter extension point usage example here.] + <extension + point="org.eclipse.remote.console.toolbar"> + <action + actionFactory="com.example.actions.MyActionFactory" + connectionType="org.eclipse.remote.serial.core.connectionType" + id="com.example.actions.MyAction"> + </action> + </extension> @@ -99,7 +98,9 @@ - [Enter API information here.] + The value of the actionFactory attribute must implement the abstract class <code>org.eclipse.remote.console.ConsoleAction</code> + +The value of the connectionType attribute should reference the id of a connectionType under the org.eclipse.remote.core.remoteServices extension point. @@ -108,9 +109,26 @@ - [Enter information about supplied implementation of this extension point.] + The package itself does not have any predefined toolbar contributions. + + + + + + /******************************************************************************* + * Copyright (c) 2016 QNX Software Systems and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * QNX Software Systems - Initial API and implementation + *******************************************************************************/ + + diff --git a/bundles/org.eclipse.remote.console/src/org/eclipse/remote/console/actions/ConsoleAction.java b/bundles/org.eclipse.remote.console/src/org/eclipse/remote/console/actions/ConsoleAction.java index 0b5d60c97d6..2dadfc2d0cb 100644 --- a/bundles/org.eclipse.remote.console/src/org/eclipse/remote/console/actions/ConsoleAction.java +++ b/bundles/org.eclipse.remote.console/src/org/eclipse/remote/console/actions/ConsoleAction.java @@ -16,32 +16,96 @@ import org.eclipse.jface.resource.ImageRegistry; import org.eclipse.remote.internal.console.Activator; /** + * An abstract class to implement basic functionality common to terminal console actions * @since 1.1 */ public abstract class ConsoleAction extends Action { + + /** + * @param id + * The action id + */ public ConsoleAction(String id) { this(id, 0); } + /** + * @param id + * The action id + * @param style + * one of AS_PUSH_BUTTON, AS_CHECK_BOX, AS_DROP_DOWN_MENU, AS_RADIO_BUTTON, + * and AS_UNSPECIFIED + */ public ConsoleAction(String id, int style) { super("", style); //$NON-NLS-1$ setId(id); } - protected void setupAction(String text, String tooltip, String image, String enabledImage, String disabledImage, + /** + * @param text + * the text for this action + * @param tooltip + * the tooltip for this action + * @param image + * the image key for this action + * @param enabledImage + * the enabled image key for this action + * @param disabledImage + * the disabled image key for this action + * @param enabled + * the enabled state for this action + */ + protected void setupAction(String text, String tooltip, + String image, String enabledImage, String disabledImage, boolean enabled) { ImageRegistry imageRegistry = Activator.getDefault().getImageRegistry(); setupAction(text, tooltip, image, enabledImage, disabledImage, enabled, imageRegistry); } - protected void setupAction(String text, String tooltip, String hoverImage, String enabledImage, - String disabledImage, boolean enabled, ImageRegistry imageRegistry) { - setupAction(text, tooltip, imageRegistry.getDescriptor(hoverImage), imageRegistry.getDescriptor(enabledImage), - imageRegistry.getDescriptor(disabledImage), enabled); + /** + * @param text + * the text for this action + * @param tooltip + * the tooltip for this action + * @param hoverImage + * the hover image key for this action + * @param enabledImage + * the enabled image key for this action + * @param disabledImage + * the disabled image key for this action + * @param enabled + * the enabled state for this action + * @param imageRegistry + * the ImageRegistry to retrieve ImageDescriptor for the keys provided + */ + protected void setupAction(String text, String tooltip, + String hoverImage, String enabledImage, String disabledImage, + boolean enabled, ImageRegistry imageRegistry) { + setupAction(text, + tooltip, + imageRegistry.getDescriptor(hoverImage), + imageRegistry.getDescriptor(enabledImage), + imageRegistry.getDescriptor(disabledImage), + enabled); } - protected void setupAction(String text, String tooltip, ImageDescriptor hoverImage, ImageDescriptor enabledImage, - ImageDescriptor disabledImage, boolean enabled) { + /** + * @param text + * the text for this action + * @param tooltip + * the tooltip for this action + * @param hoverImage + * the hover image for this action + * @param enabledImage + * the enabled image for this action + * @param disabledImage + * the disabled image for this action + * @param enabled + * the enabled state for this action + */ + protected void setupAction(String text, String tooltip, + ImageDescriptor hoverImage, ImageDescriptor enabledImage, ImageDescriptor disabledImage, + boolean enabled) { setText(text); setToolTipText(tooltip); setEnabled(enabled); diff --git a/bundles/org.eclipse.remote.console/src/org/eclipse/remote/console/actions/IConsoleActionFactory.java b/bundles/org.eclipse.remote.console/src/org/eclipse/remote/console/actions/IConsoleActionFactory.java index fff843a7a30..7f935c33051 100644 --- a/bundles/org.eclipse.remote.console/src/org/eclipse/remote/console/actions/IConsoleActionFactory.java +++ b/bundles/org.eclipse.remote.console/src/org/eclipse/remote/console/actions/IConsoleActionFactory.java @@ -16,5 +16,16 @@ import org.eclipse.core.runtime.IAdaptable; * @since 1.1 */ public interface IConsoleActionFactory { + /** + * Returns an implementation of ConsoleAction + * + * @param actionId + * The id of the action being requested + * @param connectionType + * The connection type of the terminal console + * @param adapter + * An adapter to get relevant objects for use by the ConsoleAction being created (eg. IRemoteConnection) + * @return an implementation of ConsoleAction + */ public ConsoleAction createAction(String actionId, String connectionType, IAdaptable adapter); }