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.common.api; 18 19 import com.android.annotations.Nullable; 20 import com.google.common.annotations.Beta; 21 22 /** 23 * Structure returned by onDropEnter/Move and passed to over onDropXyz methods. 24 * <p> 25 * <b>NOTE: This is not a public or final API; if you rely on this be prepared 26 * to adjust your code for the next tools release.</b> 27 * </p> 28 */ 29 @Beta 30 public class DropFeedback { 31 /** 32 * User data that the rule can use in any way it wants to carry state from one 33 * operation to another. 34 * <p/> 35 * Filled and owned by the view rule. 36 */ 37 @Nullable 38 public Object userData; 39 40 /** 41 * If true the next screen update will invoke the paint callback. 42 * <p/> 43 * Filled by the view rule to request a paint, and reset by the canvas after 44 * the paint occurred. 45 */ 46 public boolean requestPaint; 47 48 /** 49 * Set to false by the engine when entering a new view target. 50 * The view rule should set this to true if the current view target is not 51 * a valid drop zone. 52 * <p/> 53 * When set to true, the onDropped() method will not be called if the user releases 54 * the mouse button. Depending on the platform or implementation, the mouse cursor 55 * <em>may</em> reflect that the drop operation is invalid. 56 * <p/> 57 * Rationale: an operation like onDropEnter() is called each time the mouse enters 58 * a new view target and is supposed to return null when the drop cannot happen 59 * <em>at all</em> in that target. However a layout like RelativeLayout decorates 60 * potential targets with "hot spots" that are suitable drop zones, whereas some 61 * other parts of the view are not suitable drop zones. In this case the onDropEnter() 62 * or onDropMove() operation would return a {@link DropFeedback} with 63 * <code>invalidTarget=true</code>. 64 */ 65 public boolean invalidTarget; 66 67 /** 68 * Painter invoked by the canvas to paint the feedback. 69 * Filled by the view rule, called by the engine. 70 * <p/> 71 */ 72 @Nullable 73 public IFeedbackPainter painter; 74 75 /** 76 * When set to a non-null valid rectangle, this informs the engine that a drag'n'drop 77 * feedback wants to capture the mouse as long as it stays in the given area. 78 * <p/> 79 * When the mouse is captured, drop events will keep going to the rule that started the 80 * capture and the current INode proxy will not change. 81 * <p/> 82 * Filled by the view rule, read by the engine. 83 */ 84 @Nullable 85 public Rect captureArea; 86 87 /** 88 * Set to true by the drag'n'drop engine when the current drag operation is a copy. 89 * When false the operation is a move and <em>after</em> a successful drop the source 90 * elements will be deleted. 91 * <p/> 92 * Filled by the engine, read by view rule. 93 */ 94 public boolean isCopy; 95 96 /** 97 * The bounds of the drag, relative to the starting mouse position. For example, if 98 * you have a rectangular view of size 100x80, and you start dragging at position 99 * (15,20) from the top left corner of this rectangle, then the drag bounds would be 100 * (-15,-20, 100x80). 101 * <p> 102 * NOTE: The coordinate units will be in layout/view coordinates. In other words, they 103 * are unaffected by the canvas zoom. 104 */ 105 @Nullable 106 public Rect dragBounds; 107 108 /** 109 * The baseline of the primary dragged view. -1 means that the view does not have a baseline. 110 */ 111 public int dragBaseline = -1; 112 113 /** 114 * Set to true when the drag'n'drop starts and ends in the same canvas of the 115 * same Eclipse instance. 116 * <p/> 117 * Filled by the engine, read by view rule. 118 */ 119 public boolean sameCanvas; 120 121 /** 122 * Density scale for pixels. To compute the dip (device independent pixel) in the 123 * view from a layout coordinate, apply this scale. 124 */ 125 public double dipScale = 1.0; 126 127 /** 128 * Initializes the drop feedback with the given user data and paint 129 * callback. A paint is requested if the paint callback is non-null. 130 * 131 * @param userData Data stored for later retrieval by the client 132 * @param painter A callback invoked to paint the drop feedback 133 */ 134 public DropFeedback(@Nullable Object userData, @Nullable IFeedbackPainter painter) { 135 this.userData = userData; 136 this.painter = painter; 137 this.requestPaint = painter != null; 138 this.captureArea = null; 139 } 140 141 /** 142 * A message to be displayed to the user, if any. Should not contain line separators. 143 */ 144 @Nullable 145 public String message; 146 147 /** 148 * An error message to be displayed to the user, if any. Should not contain line 149 * separators. 150 */ 151 @Nullable 152 public String errorMessage; 153 154 /** 155 * A message to be displayed in a tooltip to the user, which should be short, but 156 * can be multiple lines (use embedded newlines) 157 */ 158 @Nullable 159 public String tooltip; 160 161 /** 162 * Horizontal alignment for the tooltip, or null if no preference 163 */ 164 @Nullable 165 public SegmentType tooltipX; 166 167 /** 168 * Vertical alignment for the tooltip, or null if no preference 169 */ 170 @Nullable 171 public SegmentType tooltipY; 172 173 /** 174 * A mask of the currently held keyboard modifier keys - some combination of 175 * {@link #MODIFIER1}, {@link #MODIFIER2}, {@link #MODIFIER3}, or none. 176 */ 177 public int modifierMask; 178 179 /** Bitmask value for modifier key 1 (Control on Windows/Linux, Command on Mac, etc) */ 180 public static final int MODIFIER1 = 1; 181 /** Bitmask value for modifier key 2 (Shift) */ 182 public static final int MODIFIER2 = 2; 183 /** Bitmask value for modifier key 3 (Alt on Windows/Linux, Option on Mac, etc) */ 184 public static final int MODIFIER3 = 4; 185 } 186
