Mouse 'grab and drag'?

[TomJGooding]

Perhaps this is just beyond my coding skills, but I am really struggling to understand how to add mouse 'grab and drag' functionality in Textual, like you see with the scrollbars.

I've read through the Mouse Input guide and the repo for several widgets, but I still don't understand how something like the scrollbar actually works.

If anyone could provide just a very simple code example, I would be very grateful!

[1j01]

Here's an example of dragging virtual objects around within a widget, for a simulated aquarium:

def entity_at(offset: Offset, entities: list[Entity]) -> Entity | None:
    for entity in entities:
        if entity.x <= offset.x < entity.x + entity.width and entity.y <= offset.y < entity.y + entity.height:
            return entity
    return None

class Tank(Widget):

    dragging: var[Entity | None] = var[Entity | None](None)
    drag_offset: var[Offset | None] = var[Offset | None](None)

    def on_mouse_down(self, event: events.MouseDown) -> None:
        self.capture_mouse()
        self.dragging = entity_at(event.offset, Entity.instances)
        if self.dragging is not None:
            self.drag_offset = event.offset - Offset(self.dragging.x, self.dragging.y)

    def on_mouse_up(self, event: events.MouseUp) -> None:
        self.release_mouse()
        self.dragging = None
        self.drag_offset = None

    def on_mouse_move(self, event: events.MouseMove) -> None:
        if event.button != 1:
            return
        if self.dragging is not None:
            self.dragging.x = event.offset.x - self.drag_offset.x
            self.dragging.y = event.offset.y - self.drag_offset.y

This excerpt isn't runnable directly, but the full code is pretty down to earth (other than the meta programming in the Entity class that I added for my own learning purposes.)

Note that this code is for dragging game objects (entities) which are not widgets.

If you want to drag widgets themselves around, I've implemented draggable windows for another project, so I could definitely help you out. Let me know if this is what you're looking for and I could distill this into an example for you. (Unlike the aquarium project, the code is not clean and simple, as it stands.)

[TomJGooding]

Thanks very much @1j01! I'll have a proper look at both those examples over the weekend. (MS Paint built with Textual?! That's seriously impressive!)

It was dragging widgets I was thinking of, but I hadn't even considered non-widgets so that's also really interesting.

Hopefully I can get the gist without troubling you for a distilled example, I really appreciate your help!

[TomJGooding]

Thanks again @1j01 for your examples - I think I'm finally starting to get the hang of this!

from textual import events
from textual.app import App, ComposeResult
from textual.geometry import Offset
from textual.reactive import reactive
from textual.widgets import Static


class Draggable(Static):
    DEFAULT_CSS = """
    Draggable {
        width: auto;
    }
    """

    mouse_at_drag_start: reactive[Offset | None] = reactive(None)
    offset_at_drag_start: reactive[Offset | None] = reactive(None)

    def on_mouse_down(self, event: events.MouseDown) -> None:
        self.mouse_at_drag_start = event.screen_offset
        self.offset_at_drag_start = Offset(
            round(self.styles.offset.x.value),
            round(self.styles.offset.y.value),
        )
        self.capture_mouse()

    def on_mouse_move(self, event: events.MouseMove) -> None:
        if (
            self.mouse_at_drag_start is not None
            and self.offset_at_drag_start is not None
        ):
            x = self.offset_at_drag_start.x + (
                event.screen_x - self.mouse_at_drag_start.x
            )
            y = self.offset_at_drag_start.y + (
                event.screen_y - self.mouse_at_drag_start.y
            )

            self.styles.offset = (x, y)

    def on_mouse_up(self, event: events.MouseUp) -> None:
        self.mouse_at_drag_start = None
        self.offset_at_drag_start = None
        self.release_mouse()
        event.stop()


class ExampleApp(App):
    CSS = """
    Screen {
        align: center middle
    }
    """

    def compose(self) -> ComposeResult:
        yield Draggable('Grab & move\n   __QQ\n  (_)_">\n  _)\n the mouse')


if __name__ == "__main__":
    app = ExampleApp()
    app.run()

[1j01]

Nice! Adorable example, with the mouse. 😸

• You can actually simplify it a little further with self.styles.offset = self.offset_at_drag_start + event.screen_offset - self.mouse_at_drag_start (and I can do the same in my own code!) since Offset defines __add__.
• You could use var instead of reactive (or reactive(None, repaint=False)) which might be more efficient (if it doesn't de-duplicate the repaint behind the scenes, perhaps). The efficiency surely doesn't matter here, but you might want to get in a habit of thinking about whether you need it to repaint the widget when changing the value of a reactive variable.

Anyway, good job on distilling this to an example.

[TomJGooding]

Good point about simplifying the offset, perhaps reveals I was just copying your code rather than properly understanding it!

Thanks again for your help!