1 /* 2 * Copyright (C) 2010 The Android Open Source Project 3 * 4 * Licensed under the Eclipse Public License, Version 1.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.eclipse.org/org/documents/epl-v10.php 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.android.ide.eclipse.adt.internal.editors.layout.gle2; 18 19 import com.android.utils.Pair; 20 21 import org.eclipse.swt.events.KeyEvent; 22 23 import java.util.Collections; 24 import java.util.List; 25 26 /** 27 * A gesture is a mouse or keyboard driven user operation, such as a 28 * swipe-select or a resize. It can be thought of as a session, since it is 29 * initiated, updated during user manipulation, and finally completed or 30 * canceled. A gesture is associated with a single undo transaction (although 31 * some gestures don't actually edit anything, such as a selection), and a 32 * gesture can have a number of graphics {@link Overlay}s which are added and 33 * cleaned up on behalf of the gesture by the system. 34 * <p/> 35 * Gestures are typically mouse oriented. If a mouse wishes to integrate 36 * with the native drag & drop support, it should also implement 37 * the {@link DropGesture} interface, which is a sub interface of this 38 * {@link Gesture} interface. There are pros and cons to using native drag 39 * & drop, so various gestures will differ in whether they use it. 40 * In particular, you should use drag & drop if your gesture should: 41 * <ul> 42 * <li> Show a native drag & drop cursor 43 * <li> Copy or move data, especially if this applies outside the canvas 44 * control window or even the application itself 45 * </ul> 46 * You might want to avoid using native drag & drop if your gesture should: 47 * <ul> 48 * <li> Continue updating itself even when the mouse cursor leaves the 49 * canvas window (in a drag & gesture, as soon as you leave the canvas 50 * the drag source is no longer informed of mouse updates, whereas a regular 51 * mouse listener is) 52 * <li> Respond to modifier keys (for example, if toggling the Shift key 53 * should constrain motion as is common during resizing, and so on) 54 * <li> Use no special cursor (for example, during a marquee selection gesture we 55 * don't want a native drag & drop cursor) 56 * </ul> 57 * <p/> 58 * Examples of gestures: 59 * <ul> 60 * <li>Move (dragging to reorder or change hierarchy of views or change visual 61 * layout attributes) 62 * <li>Marquee (swiping out a rectangle to make a selection) 63 * <li>Resize (dragging some edge or corner of a widget to change its size, for 64 * example to some new fixed size, or to "attach" it to some other edge.) 65 * <li>Inline Editing (editing the text of some text-oriented widget like a 66 * label or a button) 67 * <li>Link (associate two or more widgets in some way, such as an 68 * "is required" widget linked to a text field) 69 * </ul> 70 */ 71 public abstract class Gesture { 72 /** Start mouse coordinate, in control coordinates. */ 73 protected ControlPoint mStart; 74 75 /** Initial SWT mask when the gesture started. */ 76 protected int mStartMask; 77 78 /** 79 * Returns a list of overlays, from bottom to top (where the later overlays 80 * are painted on top of earlier ones if they overlap). 81 * 82 * @return A list of overlays to paint for this gesture, if applicable. 83 * Should not be null, but can be empty. 84 */ createOverlays()85 public List<Overlay> createOverlays() { 86 return Collections.emptyList(); 87 } 88 89 /** 90 * Handles initialization of this gesture. Called when the gesture is 91 * starting. 92 * 93 * @param pos The most recent mouse coordinate applicable to this 94 * gesture, relative to the canvas control. 95 * @param startMask The initial SWT mask for the gesture, if known, or 96 * otherwise 0. 97 */ begin(ControlPoint pos, int startMask)98 public void begin(ControlPoint pos, int startMask) { 99 mStart = pos; 100 mStartMask = startMask; 101 } 102 103 /** 104 * Handles updating of the gesture state for a new mouse position. 105 * 106 * @param pos The most recent mouse coordinate applicable to this 107 * gesture, relative to the canvas control. 108 */ update(ControlPoint pos)109 public void update(ControlPoint pos) { 110 } 111 112 /** 113 * Handles termination of the gesture. This method is called when the 114 * gesture has terminated (either through successful completion, or because 115 * it was canceled). 116 * 117 * @param pos The most recent mouse coordinate applicable to this 118 * gesture, relative to the canvas control. 119 * @param canceled True if the gesture was canceled, and false otherwise. 120 */ end(ControlPoint pos, boolean canceled)121 public void end(ControlPoint pos, boolean canceled) { 122 } 123 124 /** 125 * Handles a key press during the gesture. May be called repeatedly when the 126 * user is holding the key for several seconds. 127 * 128 * @param event The SWT event for the key press, 129 * @return true if this gesture consumed the key press, otherwise return false 130 */ keyPressed(KeyEvent event)131 public boolean keyPressed(KeyEvent event) { 132 return false; 133 } 134 135 /** 136 * Handles a key release during the gesture. 137 * 138 * @param event The SWT event for the key release, 139 * @return true if this gesture consumed the key press, otherwise return false 140 */ keyReleased(KeyEvent event)141 public boolean keyReleased(KeyEvent event) { 142 return false; 143 } 144 145 /** 146 * Returns whether tooltips should be display below and to the right of the mouse 147 * cursor. 148 * 149 * @return a pair of booleans, the first indicating whether the tooltip should be 150 * below and the second indicating whether the tooltip should be displayed to 151 * the right of the mouse cursor. 152 */ getTooltipPosition()153 public Pair<Boolean, Boolean> getTooltipPosition() { 154 return Pair.of(true, true); 155 } 156 } 157