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