| <!-- |
| ~ Copyright (C) 2018 The Android Open Source Project |
| ~ |
| ~ Licensed under the Apache License, Version 2.0 (the "License"); |
| ~ you may not use this file except in compliance with the License. |
| ~ You may obtain a copy of the License at |
| ~ |
| ~ http://www.apache.org/licenses/LICENSE-2.0 |
| ~ |
| ~ Unless required by applicable law or agreed to in writing, software |
| ~ distributed under the License is distributed on an "AS IS" BASIS, |
| ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| ~ See the License for the specific language governing permissions and |
| ~ limitations under the License. |
| --> |
| |
| <!-- For better readability, Please open this file in the browser --> |
| |
| **Design Doc of Notch** |
| |
| *Last updated: March 27th 2018* |
| |
| Overview |
| ===== |
| |
| Notch is an area which snaps the dragged element during drag and drop interaction. |
| |
| “Snap” means that the dragged element will be “attracted” to the Notch position (“value”) when the mouse is close to it |
| (i.e within the “gap”). |
| |
| How to Use |
| ===== |
| |
| The snappable component must implement the `Notch.Provider` interface and add its `Notch` in the implementation.<br> |
| The class that wants to interact with Notches must use `TargetSnapper`, which provides several APIs to snap to the `Notch`. |
| |
| When `TargetSnapper` tries to snap the `Notch`, it returns the optional value. If it really find a Notch to snap for the given coordinate, |
| the optional value will be present. However, if there is no Notch effects on the given coordinate, the returned value is not present. |
| |
| |
| `TargetSnapper` |
| ----- |
| The class to interact with `Notch`. This class provides the functions to collect the `Notch` from the `Notch.Provider` and snap to them. |
| |
| `Notch` |
| ----- |
| The class describes the information of snappable area. Using predefined `Notch`es such like `Notch.Horizontal`, `Notch.Vertical`, |
| `Notch.Circular` is recommended. If it really needs a customized Notch, override `Notch.isSnappable()`. |
| |
| `Notch.Provider` |
| ----- |
| Each class that provides `Notch`es must implements this interface. |
| |
| `Notch.Action` |
| ----- |
| Used to attach a runnable `Notch` that will be triggered on the snapped Notch when calling `TargetSnapper.applyNotches()` |
| |
| |
| Common Usage Steps |
| ----- |
| * Create `TargetSnapper` |
| * Call `TargetSnapper.gatherNotches(SceneComponent)`, this will collect the `Notch` related to the given SceneComponent |
| * Call `TargetSnapper.trySnap[Horizontal|Vertical|Circular]()`, this will try to snap the `Notch` on the given type. |
| * If you need to get the `Target` which offers the snapped `Notch`, use `TargetSnapper.getSnapped[Horizontal|Vertical|Circular]`. |
| * You can also render the snapped `Notch` by calling `TargetSnapper.renderSnappedNotches()`. |
| * If you want to run the attached `Notch.Action` on the snapped `Notch`, use `TargetSnapper.applyNotches`. |
| * Use `TargetSnapper.reset()` to reset the status of `TargetSnapper`. This will clear the collected Notches and snapped Notches. |
| This function should be called after interaction is done, or before it is started. |
| This step is important since the snapped `Notch`(es) must be cleared before next usage. |
| |
| <!-- Markdeep: --><style class="fallback">body{visibility:hidden;white-space:pre;font-family:monospace}</style><script src="markdeep.min.js"></script><script src="https://casual-effects.com/markdeep/latest/markdeep.min.js"></script><script>window.alreadyProcessedMarkdeep||(document.body.style.visibility="visible")</script> |
