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 &amp; 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  * &amp; drop, so various gestures will differ in whether they use it.
40  * In particular, you should use drag &amp; drop if your gesture should:
41  * <ul>
42  * <li> Show a native drag &amp; 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 &amp; 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 &amp; 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 &amp; 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