**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.
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.