Source Code Cross Referenced for IFocusService.java in  » IDE-Eclipse » ui-workbench » org » eclipse » ui » swt » Java Source Code / Java DocumentationJava Source Code and Java Documentation

001:        /*******************************************************************************
002:         * Copyright (c) 2007 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.swt;
011:
012:        import org.eclipse.swt.widgets.Control;
013:
014:        /**
015:         * Tracks focusGained and focusLost events for a Control registered with this
016:         * service, and provides the control and its registered ID as variables to the
017:         * application evaluation context for evaluation be the various services.
018:         * <p>
019:         * This service provides 2 variables, activeFocusControl (a Control) and
020:         * activeFocusControlId (the ID registered with the service).
021:         * </p>
022:         * <p>
023:         * You can use this service to provide default cut/copy/paste/selectAll for
024:         * specific text controls outside of the normal workbench part lifecycle, like a
025:         * control contributed to the trim. For example:
026:         * </p>
027:         * <p>
028:         * 
029:         * <pre>
030:         * &lt;handler
031:         *      class=&quot;org.eclipse.ui.internal.handlers.WidgetMethodHandler:paste&quot;
032:         *      commandId=&quot;org.eclipse.ui.edit.paste&quot;&gt;
033:         *   &lt;activeWhen&gt;
034:         *      &lt;with variable=&quot;activeFocusControlId&quot;&gt;
035:         *         &lt;equals value=&quot;org.eclipse.ui.tests.focusText&quot;/&gt;
036:         *      &lt;/with&gt;
037:         *   &lt;/activeWhen&gt;
038:         * &lt;/handler&gt;
039:         * </pre>
040:         * 
041:         * </p>
042:         * 
043:         * @see org.eclipse.ui.ISources
044:         * @since 3.3
045:         */
046:        public interface IFocusService {
047:            /**
048:             * Use the value to provide default copy behaviour in a handler element
049:             * class attribute.
050:             */
051:            public static final String COPY_HANDLER = "org.eclipse.ui.internal.handlers.WidgetMethodHandler:copy"; //$NON-NLS-1$
052:
053:            /**
054:             * Use the value to provide default paste behaviour in a handler element
055:             * class attribute.
056:             */
057:            public static final String PASTE_HANDLER = "org.eclipse.ui.internal.handlers.WidgetMethodHandler:paste"; //$NON-NLS-1$
058:
059:            /**
060:             * Use the value to provide default cut behaviour in a handler element class
061:             * attribute.
062:             */
063:            public static final String CUT_HANDLER = "org.eclipse.ui.internal.handlers.WidgetMethodHandler:cut"; //$NON-NLS-1$
064:
065:            /**
066:             * Use the value to provide default select all behaviour in a handler
067:             * element class attribute.
068:             */
069:            public static final String SELECT_ALL_HANDLER = "org.eclipse.ui.internal.handlers.SelectAllHandler"; //$NON-NLS-1$
070:
071:            /**
072:             * A Control for which the service will track focus. When in focus, this
073:             * Control and its ID will be provided as variables to core expressions for
074:             * the various services, as activeFocusControl and activeFocusControlId
075:             * respectively.
076:             * <p>
077:             * A control must only be registered once, but different controls can be
078:             * registered with the same ID. Expressions evaluated against the
079:             * activeFocusControlId would then be true for all of the controls thus
080:             * registered.
081:             * </p>
082:             * <p>
083:             * We will remove ourselves as a listener when the Control is disposed.
084:             * </p>
085:             * 
086:             * @param control
087:             *            the control. Must not be <code>null</code>. If the control
088:             *            is already registered with this service this call is a no-op.
089:             * @param id
090:             *            an ID for this control. Must not be <code>null</code>.
091:             */
092:            public void addFocusTracker(Control control, String id);
093:
094:            /**
095:             * No longer track focus events for this control. Use this method when the
096:             * control should no longer be tracked, but is not disposed.
097:             * 
098:             * @param control
099:             *            the control registered with the service. Must not be
100:             *            <code>null</code>.
101:             */
102:            public void removeFocusTracker(Control control);
103:        }