{"id":"coffilhg/greatuidrag","name":"greatuidrag","scope":"coffilhg","platform":"roblox","description":"Draggable UIs made easy!","version":"2.0.1","latest":"2.0.1","versions":["0.0.1","0.0.2","1.0.0","2.0.0","2.0.1"],"license":"MPL-2.0","licenseRating":"caution","licenseCaveats":["File-level copyleft: if you modify this package's own source files, those modified files must be made available under MPL-2.0. Using it unmodified in a closed-source game is fine."],"licenseVerified":true,"dependencies":{"coffilhg/coffeeobjects":{"version":"^2.4.0","alias":"CoffeeObjects"},"coffilhg/guicompatibility":{"version":"^1.0.0","alias":"GUICompatibility"},"data-oriented-house/lemonsignal":{"version":"^2.0.0","alias":"LemonSignal"}},"integrity":"624172c6260af3ac7ed7d23a32a941cabb31b359b965b63719e294d25e17e4a9","likes":0,"downloads":0,"install":"forest install coffilhg/greatuidrag","url":"https://forest.dev/p/roblox/coffilhg/greatuidrag","files":"https://api.forest.dev/ai/package/roblox/coffilhg/greatuidrag/files","readme":"# GreatUIDrag\r\n\r\nDraggable UIs made easy!\r\nSupports desktop and mobile, GUI insets, anchor points, viewport resizing, and CSS-like padding limits. Console support is untested but should work for cursor-based input.\r\n\r\n\r\n\r\n## Available Here!\r\n- **[This repository](src/init.luau) ~ [src/init.luau](src/init.luau)**\r\n- **[Wally](<https://wally.run/package/coffilhg/greatuidrag>)**\r\n\r\n    ```toml\r\n    GreatUIDrag = \"coffilhg/greatuidrag@2.0.1\"\r\n    ```\r\n- **[Rotriever](<https://github.com/Coffilhg/Useful-Modules/releases/tag/vGreatUIDrag/2.0.1>)**\r\n\r\n    ```toml\r\n    GreatUIDrag = \"github.com/Coffilhg/Useful-Modules@GreatUIDrag/2.0.1\"\r\n    ```\r\n\r\n\r\n\r\n---\r\n\r\n## Features\r\n- Smooth spring interpolation (no Tween spam, thx to @crusherfire)\r\n- CSS-like padding\r\n- Optionally multiple drag handles\r\n- Sensibility, speed and damping control\r\n- Automatically handles\r\n    - IgnoreGuiInset changes\r\n    - AnchorPoint\r\n    - Viewport resizing (Non-fullscreen players and mobile players rotating their screen)\r\n- Events for contact, start, release, completion and position changes (Click vs drag detection)\r\n\r\n---\r\n\r\n## Usage\r\n\r\nPlace the module and its dependencies somewhere accessible (e.g. `ReplicatedStorage`):\r\n> Here's how it looks when you run `rojo serve test.project.json` of this repository\r\n> \r\n> (you must have rojo, wally, wally-package-types and previously download dependencies (e.g. with `wally install && rojo sourcemap test.project.json --output sourcemap.json && wally-package-types -s sourcemap.json Packages/`))\r\n```\r\nPackages\r\n├── _Index\r\n├── CoffeeObjects\r\n├── GUICompatibility\r\n├── GreatUIDrag\r\n│   └── _Spring\r\n└── LemonSignal\r\n```\r\n\r\nThen require it:\r\n```lua\r\nlocal GreatUIDrag = require(path.To.GreatUIDrag)\r\n```\r\n\r\n---\r\n\r\n## Quick Start\r\n\r\n```lua\r\nGreatUIDrag(\r\n    Frame,          -- GuiObject to move\r\n    Frame.Header    -- Drag handle (TextButton / ImageButton) -- Optional for V2.0.0+\r\n)\r\n```\r\n\r\nor more explicit\r\n\r\n```lua\r\nlocal drag = GreatUIDrag(\r\n    Frame,                  -- GuiObject to move\r\n    Frame.Header,           -- Drag handle (TextButton / ImageButton)\r\n    1,                      -- Damping (Less = more like jelly)\r\n    27,                     -- Speed (More = faster interpolation)\r\n    {UDim.new(0.04, 8)},    -- Padding (Top, Right, Bottom, Left)\r\n    1,                      -- Sensibility (Useful for UI bigger than screen)\r\n    0.24                    -- Drag Start Delay (Useful to ignore simple clicks)\r\n)\r\n```\r\n\r\n---\r\n\r\n## API\r\n\r\n```lua\r\nGreatUIDrag(\r\n    dragElement: GuiObject,\r\n    dragHandle: ( DragHandle | {DragHandle} )?,\r\n    damping: number?,\r\n    speed: number?,\r\n    paddingOptions: ( number | UDim | {number | UDim} )?,\r\n    sensibilityMultiplier: number?,\r\n    dragStartDelay: number?\r\n): DragElement\r\n```\r\n\r\n## Parameters\r\n\r\n### `dragElement`\r\n> The UI object that will move.\r\n\r\n### `dragHandle` (optional for V2.0.0+)\r\n> A `TextButton` or `ImageButton`\r\n>\r\n> OR an array (table) of them\r\n>\r\n> More can be added using `:AddHandle` for V2.0.0+\r\n\r\n### `damping` (optional)\r\n> Spring damping factor\r\n> Default = `1`\r\n>\r\n> Lower = bouncier\r\n> Higher = stiffer\r\n\r\n### `speed` (optional)\r\n> Spring speed\r\n>\r\n> Default = `27 / sensibilityMultiplier`\r\n\r\n### `paddingOptions` (optional)\r\n> CSS-like syntax:\r\n\r\n| Input                      | Result                                                                       |\r\n|----------------------------|------------------------------------------------------------------------------|\r\n| Empty (`nil`) or `{}`      | Defaults to 30px padding on all sides                                        |\r\n| `x` or `{x}`               | All sides have `x` padding                                                   |\r\n| `{y, x}`                   | Horizontal (top+bottom) padding is `y`; Vertical (right+left) padding is `x` |\r\n| `{y1, x, y2}`              | Top padding = `y1`, sides (right+left) padding = `x`, Bottom padding = `y2`  |\r\n| `top, right, bottom, left` | full control                                                                 |\r\n\r\n> Each value can be an UDim or a number, which will be converted into UDim.new(0, number) (pixels)\r\n\r\n### `sensibilityMultiplier` (optional)\r\n> Drag sensitivity\r\n> \r\n> Default = `1`\r\n\r\n### `dragStartDelay` (optional)\r\n> Minimal Press & Hold time (Delay) for Drag to start\r\n>\r\n> `OnDragStarted` Fires once this time has passed, after the `OnDragContact`, which fires the instant the DragElement is Pressed\r\n> \r\n> Default = `0.24`\r\n\r\n## Returned Object (`DragElement`) Methods\r\n\r\n```lua\r\nlocal MyDragElement = GreatUIDrag(...)\r\n```\r\n\r\n### `MyDragElement:AddHandle(dragHandle: ( DragHandle | {DragHandle} )?)`\r\n> \"`type DragHandle = (TextButton | ImageButton | GuiButton)`\"\r\n>\r\n> Adds a `TextButton` / `ImageButton` / `GuiButton`, or an array (table) of them, as additional drag handles (or the main one if none were added previously at creation).\r\n\r\n### `MyDragElement:Destroy()`\r\n> Cancels active drag on this `DragElement` and disconnects all signals involved (including all Event signals)\r\n>\r\n> It is silent, without `OnDragReleased` / `OnDragCompleted`\r\n>\r\n> Called automatically when the `dragElement` is destroyed (anything that triggers `dragElement.Destroying`)\r\n>\r\n> Does **not** destroy the `dragElement` or the handles themselves.\r\n>\r\n> (no arguments)\r\n\r\n### `MyDragElement:InitDrag(triggerHandle: DragHandle)`\r\n> Activates dragging (as if client started using one of the drag handles), if this `DragElement` isn't active already\r\n> \r\n> `triggerHandle` is passed to the events\r\n\r\n### `MyDragElement:IsDestroyed(): boolean`\r\n> Returns a boolean on whether the `DragElement` is destroyed. If it is, it shall not be used and the reference shall be `nil`lified or overwritten\r\n>\r\n> (no arguments)\r\n\r\n### `MyDragElement:Reposition()`\r\n> Immediately repositions the element to the current spring state\r\n>\r\n> (no arguments)\r\n\r\n### `MyDragElement:SetPosition(position: UDim2?)`\r\n> Places the element immediately and resets the spring, without animating\r\n> \r\n> If `typeof(position) ~= \"UDim2\"` (e.g. not given), it uses the mouse location\r\n\r\n### `MyDragElement:Stop()`\r\n> Stops active dragging (client input signals) but allows spring to reach the latest goal\r\n>\r\n> (no arguments)\r\n\r\n## Returned Object (`DragElement`) Events (V2.0.0+)\r\nAll of the events are **Signal** Objects instantiated via **LemonSignal**\r\n> (a new dependency introduced in v2.0.0)\r\n\r\n| Event                  | Arguments                                | Fires                                                                 |\r\n|------------------------|------------------------------------------|-----------------------------------------------------------------------|\r\n| `OnDragContact`        | `triggerHandle`                          | A handle was pressed; First contact with the dragElement made                                                                                                                            |\r\n| `OnDragStarted`        | `triggerHandle`                          | The pointer moved after `dragStartDelay` (a real drag); Fires after OnDragContact and dragStartDelay if not OnDragReleased                                                               |\r\n| `OnDragReleased`       | `finalGoal, wasDragged, triggerHandle`   | Released, or another element started dragging; the spring keeps going; Fires after dragElement gets released or another dragElement is starting, continues moving towards the final goal |\r\n| `OnDragCompleted`      | `finalGoal, wasDragged, triggerHandle`   | The spring settled at the final goal; Fires after the final goal was reached                                                                                                             |\r\n| `OnPositionChanged`    | `currentAbsoluteX, currentAbsoluteY`     | The element was repositioned (the offsets written to `Position`); Fires on Reposition / UIS.InputChanged while used                                                                      |\r\n\r\n`wasDragged` is `true` if `OnDragStarted` fired, otherwise `nil`, so you can tell a click from a drag:\r\n> `wasDragged` is an alias for `IsDragStartFiredBeforeReleased` (how it is commented in the source)\r\n\r\nExample usage:\r\n```lua\r\nMyDragElement.OnDragReleased:Connect(function(finalGoal, wasDragged, handle)\r\n    if not wasDragged then\r\n        print(\"just a click on\", handle)\r\n    end\r\nend)\r\n```\r\n\r\n---\r\n\r\n## Notes\r\n- Only one active drag is allowed at a time (intentional)\r\n    - Pressing another element's handle stops this one (its `OnDragReleased` fires)\r\n- Uses `RunService.Heartbeat` only while active or on-the-way to complete the latest goal\r\n- Automatically updates bounds based on:\r\n    - Viewport resize (`game.Workspace.CurrentCamera:GetPropertyChangedSignal(\"ViewportSize\")`)\r\n    - AnchorPoint change (`dragElement:GetPropertyChangedSignal(\"AnchorPoint\")`)\r\n    - GuiInset change (`GUICompatibility:GetGuiInsetSize().Value`)\r\n- The element won't move unless it's inside a `ScreenGui`. This is re-checked when its parent changes\r\n- To react to a `DragElement` being destroyed, connect to the `dragElement`'s own `Destroying` event. Check `:IsDestroyed()` if you need to know later\r\n- Setting `dragElement.Parent = nil` is not `dragElement:Destroy()`, therefore it does not automatically call `DragElement:Destroy()`\r\n\r\n---\r\n\r\n## Dependencies\r\n- [GUICompatibility](https://github.com/Coffilhg/Useful-Modules/tree/GUICompatibility)\r\n- [CoffeeObjects](https://github.com/Coffilhg/Useful-Modules/tree/CoffeeObjects)\r\n- [_Spring](https://create.roblox.com/store/asset/71132874095126/Spring-Module) (by @crusherfire | https://www.roblox.com/users/80102935/profile)\r\n- [LemonSignal](<https://github.com/Data-Oriented-House/LemonSignal>)\r\n\r\n## License & Attribution\r\n\r\nThis module is licensed under the **Mozilla Public License 2.0 (MPL-2.0)**.\r\n\r\n#### What this means for Roblox Developers:\r\n* **Use & Modify:** You can freely use this module in any public, private, or commercial Roblox game.\r\n* **File-Level Copyleft:** If you modify the source code of this module itself, you must make your modified version of the module publicly available under the MPL 2.0.\r\n* **No Viral Code Leakage:** Including this module in your game does **not** force you to open-source your other game scripts, UI layouts, or proprietary codebase. \r\n\r\nSee the full terms in the [LICENSE](LICENSE) file.\r\n\r\nAttribution to all dependencies is included in [Notice](NOTICE)\r\n\r\nCopyright © 2026 @Coffilhg (Roblox UserId 517222346)","readmeTruncated":false}