Click and Drag Actors

By the end of this section, we'll be able to click and drag on the actors in our actor menu. We'll have a visual indicator follow our mouse as we drag our actor, even outside of our primary window:

To signal that the user has started dragging an actor from the menu, we need a way for the Actor instance to communicate this action. We'll achieve this by defining and registering a custom SDL event type specifically for this purpose.

1// ...
2
3namespace UserEvents{
4#ifdef WITH_EDITOR
5  inline Uint32 ACTOR_DRAG{
6    SDL_RegisterEvents(1)};
7#endif
8}
9
10// ...

First, we'll add a HasMouseFocus() method to Actor to specifically check if the cursor is currently over that particular actor's area. This function will need to query the ParentScene to ensure the main window is active before checking the coordinates against the actor's Rect.

Because this new function relies on the full definition of Scene (which isn't available in Actor.h - we've only forward-declared it), we need to add a new source file for this. To keep our header file concise, we'll move our HandleEvent() definition over to that new source file too.

We'll declare HasMouseFocus() and HandleEvent() in Actor.h and implement them in a corresponding Editor/Actor.cpp file, where we can safely include Editor/Scene.h.

1// ...
2
3namespace Editor {
4class Scene;
5class Actor {
6public:
7  // ...
8  bool HasMouseFocus() const;
9  virtual void HandleEvent(const SDL_Event& E);
10  // ...
11};
12}

Inside Editor/Actor.cpp, the Actor::HasMouseFocus() function first defers to the Scene: if the parent scene doesn't have mouse focus, we know the Actor can't possibly have mouse focus, so we return false. This ensures we only consider hover checks when the editor window is active.

Assuming the scene has focus, SDL_GetMouseState() fetches the mouse coordinates within that scene's window. These coordinates are then compared against the actor's boundaries, defined by Rect.

If the coordinates lie within the horizontal range (Rect.x to Rect.x + Rect.w) and the vertical range (Rect.y to Rect.y + Rect.h), the actor is considered hovered, and true is returned. Otherwise, false indicates the mouse is elsewhere.

1#include "Editor/Actor.h"
2#include "Editor/Scene.h"
3
4using namespace Editor;
5
6bool Actor::HasMouseFocus() const {
7  if (!ParentScene.HasMouseFocus()) {
8    return false;
9  }
10
11  float x, y;
12  SDL_GetMouseState(&x, &y);
13
14  if (
15    x < Rect.x ||
16    x > Rect.x + Rect.w ||
17    y < Rect.y ||
18    y > Rect.y + Rect.h
19  ) {
20    return false;
21  }
22
23  return true;
24}

The Actor::HandleEvent() implementation filters for the specific interaction we care about: a left mouse button press. If an event represents a left-click, it's type will be SDL_EVENT_MOUSE_BUTTON_DOWN, and the SDL_MouseButtonEvent's button value will be SDL_BUTTON_LEFT.

If both are true, we then also verify HasMouseFocus() to confirm the click landed within this actor's bounds.

Upon confirmation, we prepare our custom event. An SDL_Event struct called DragEvent is initialized with the type UserEvents::ACTOR_DRAG.

The key piece of information - which actor was clicked - is attached by assigning this (a pointer to the current Actor object) to DragEvent.user.data1. This event, carrying the actor pointer, is then injected into the event queue via SDL_PushEvent(&DragEvent).

1// ...
2#include "Config.h"
3
4// ...
5
6void Actor::HandleEvent(const SDL_Event& E) {
7  if (
8    E.type == SDL_EVENT_MOUSE_BUTTON_DOWN &&
9    E.button.button == SDL_BUTTON_LEFT &&
10    HasMouseFocus()
11  ) {
12    SDL_Event DragEvent{UserEvents::ACTOR_DRAG};
13    DragEvent.user.data1 = this;
14    SDL_PushEvent(&DragEvent);
15  }
16}

To make the dragging action clear, we need a visual indicator that follows the mouse. When the ACTOR_DRAG event occurs, we should display the image of the selected actor near the cursor.

The best way to ensure this indicator remains visible even if the mouse moves outside the main editor window is to use a separate, dedicated SDL_Window. This approach allows the tooltip to float freely above the main window and others.

As we introduced previously , SDL lets us create windows with special characteristics suitable for tooltips.

We will create an Editor::ActorTooltip class to manage this process. It will be responsible for:

• creating the tooltip SDL_Window with appropriate flags
• listening for the ACTOR_DRAG event
• showing/hiding the window when drag interactions begin and end
• during drag actions, continously moving the tooltip window to be near the the mouse cursor
• drawing the dragged actor's image onto its surface

Our functions to accomplish all of these tasks look like this, and we'll walk through implementing them next:

1#pragma once
2#include <SDL3/SDL.h>
3#include "Actor.h"
4
5namespace Editor{
6class Scene;
7
8class ActorTooltip {
9public:
10  ActorTooltip(Scene& ParentScene);
11  ~ActorTooltip();
12  ActorTooltip(const ActorTooltip&) = delete;
13  ActorTooltip& operator=(const ActorTooltip&)
14  = delete;
15  void Render();
16  void Tick(float DeltaTime);
17  void PositionWindow();
18  void HandleEvent(const SDL_Event& E);
19  void SetIsVisible(bool NewVisibility);
20
21  SDL_Surface* GetSurface() const {
22    return SDL_GetWindowSurface(SDLWindow);
23  }
24
25private:
26  bool isVisible{false};
27  SDL_Window* SDLWindow{nullptr};
28  Actor* DragActor{nullptr};
29  Scene& ParentScene;
30};
31}

Constructing Tooltips

The constructor for ActorTooltip, defined in its .cpp file, focuses on creating the specialized SDL_Window.

As we saw previously, SDL3 requires tooltip and popup windows to have a parent window which, in this case, will be the window we're currently using for our primary program. We can retrieve this parent window from our ParentScene.

We use SDL_CreatePopupWindow() to create the window, passing flags combined with | to specify its behavior:

• SDL_WINDOW_HIDDEN: Ensures the tooltip is initially hidden.
• SDL_WINDOW_TOOLTIP: Identifies this window as a tooltip to the OS.
• SDL_WINDOW_BORDERLESS: Creates a window without any standard decorations like title bars or borders.
• SDL_WINDOW_ALWAYS_ON_TOP: Keeps the tooltip window rendered above the main application window and potentially other applications.
• SDL_WINDOW_NOT_FOCUSABLE: Ensures the tooltip never steals input focus, allowing the main window to continue receiving keyboard and mouse events even while the tooltip is active.

The remaining arguments we need to create the window are its position (x and y) and size (w and h). We'll just pass 0, 0, 100, and 100 as this stage. These values aren't important - we'll dynamically update the position and size of the window later, when it becomes visible.

1#include "ActorTooltip.h"
2#include "Scene.h"
3
4using namespace Editor;
5
6ActorTooltip::ActorTooltip(Scene& ParentScene)
7  : ParentScene{ParentScene}
8{
9  SDLWindow = SDL_CreatePopupWindow(
10    ParentScene.GetWindow().GetRaw(),
11    0, 0, 100, 100,
12    SDL_WINDOW_HIDDEN
13    | SDL_WINDOW_TOOLTIP
14    | SDL_WINDOW_BORDERLESS
15    | SDL_WINDOW_ALWAYS_ON_TOP
16    | SDL_WINDOW_NOT_FOCUSABLE
17  );
18  CheckSDLError("Creating Tooltip Window");
19}

Destroying and Copying Tooltips

Just like our main Editor::Window, the ActorTooltip class manages an SDL_Window resource. Therefore, it needs a destructor (~ActorTooltip) to ensure proper cleanup when an ActorTooltip object goes out of scope or is destroyed.

In our program, we expect our Scene and therefore our Tooltip to be alive for the entire duration of our program, so this shouldn't happen, but it's better to be proactive.

The destructor checks if SDL's video subsystem is still initialized using SDL_WasInit(SDL_INIT_VIDEO). If SDL has already shut down, the windows would have been cleaned up globally, so we don't need to do anything.

Otherwise, if the SDLWindow pointer is valid (not nullptr), we explicitly destroy the tooltip window using SDL_DestroyWindow().

1// ...
2
3ActorTooltip::~ActorTooltip() {
4  if (!SDL_WasInit(SDL_INIT_VIDEO)) return;
5  if (SDLWindow) {
6    SDL_DestroyWindow(SDLWindow);
7  }
8}

Positioning Tooltips

The PositionWindow() function is responsible for moving the tooltip window to follow the mouse cursor. We want the tooltip to appear right next to the cursor, creating the illusion that the user is dragging the actor image directly.

It uses SDL_GetMouseState() to get the current mouse coordinates (x, y) relative to the primary window. It then calls SDL_SetWindowPosition(), passing the SDLWindow pointer and these x and y coordinates cast to int, instantly repositioning the tooltip window to the cursor's location.

1// ...
2
3void ActorTooltip::PositionWindow() {
4  float x, y;
5  SDL_GetMouseState(&x, &y);
6  SDL_SetWindowPosition(SDLWindow, int(x), int(y));
7}

This works because our tooltip window is a child of our primary window, thus its position is relative to that parent.

If our tooltip was a regular window, its position would instead be set within the global screen coordinates. If we wanted to get our mouse position within that coordinate system, we'd use SDL_GetGlobalMouseState() instead of the SDL_GetMouseState() function we're using here.

Showing and Hiding Tooltips

We need a controlled way to show and hide the tooltip window. Creating and destroying windows frequently is inefficient, so toggling visibility is preferred.

The SetIsVisible() method manages this state. It takes a boolean Visible argument. It updates the internal isVisible flag and then calls either SDL_ShowWindow() if Visible is true, or SDL_HideWindow() if Visible is false:

This synchronizes the internal state with the actual visibility of the SDL_Window.

1// ...
2
3void ActorTooltip::SetIsVisible(bool Visible) {
4  isVisible = Visible;
5  if (isVisible) {
6    SDL_ShowWindow(SDLWindow);
7  } else {
8    SDL_HideWindow(SDLWindow);
9  }
10}

Handling Tooltip Events

The ActorTooltip::HandleEvent() method listens for the specific event that signals the start of a drag: our custom UserEvents::ACTOR_DRAG.

When it receives an event of this type, it knows it needs to become active. It first calls SetIsVisible(true) to make the tooltip window appear.

It then retrieves the pointer to the Actor being dragged, which we stored in E.user.data1 when pushing the event. It casts this void* back to an Actor* and stores it in the DragActor member variable for later use. Later, we'll render this actor's image in our tooltip window.

1// ...
2
3void ActorTooltip::HandleEvent(
4  const SDL_Event& E
5) {
6  using namespace UserEvents;
7  if (E.type == ACTOR_DRAG) {
8    SetIsVisible(true);
9    DragActor = static_cast<Actor*>(
10      E.user.data1
11    );
12  }
13}

Tooltip Ticking

In the Tick() function, we handle the continuous aspects of the tooltip's behavior. The initial if (!isVisible) return; ensures we only process logic when the tooltip should be active.

The first task of our Tick() function is to determine if the drag action is still happening or if the user has ended it. To detect this, we can get the current mouse button states using SDL_GetMouseState(). We test if the bit corresponding to the left mouse button - SDL_BUTTON_MASK(SDL_BUTTON_LEFT) - is set in the returned mask.

If it's not set, the user has let go, so we hide the tooltip using SetIsVisible(false). If the button is still held down, the drag continues, and we call PositionWindow() to keep the tooltip aligned with the cursor.

1// ...
2
3void ActorTooltip::Tick(float DeltaTime) {
4  if (!isVisible) return;
5
6  auto Buttons{
7    SDL_GetMouseState(nullptr, nullptr)
8  };
9  if (!(Buttons & SDL_BUTTON_MASK(SDL_BUTTON_LEFT))) {
10    SetIsVisible(false);
11  } else {
12    PositionWindow();
13  }
14}

Rendering Tooltips

The ActorTooltip::Render() function is responsible for drawing the content inside the tooltip window.

We'll implement the actual rendering in the next steps. For now, we'll provide an empty function body just so the code compiles. This allows us to integrate the ActorTooltip into the Scene's render loop without causing errors, even though it won't visually draw anything yet.

1// ...
2
3void ActorTooltip::Render() {
4  // We'll implement this next...
5}

Adding the Tooltip to the Scene

To integrate our new tooltip system, we need to instantiate ActorTooltip within the Editor::Scene. We'll add it as a member variable and ensure its HandleEvent(), Tick(), and Render() methods are called from the corresponding Scene methods.

Note that our ActorTooltip constuctor is accessing the ParentWindow of our scene, so we should ensure the ParentWindow variable is initialized before our ActorTooltip is constructed:

src/Editor/Scene.h

1// ...
2#include "ActorTooltip.h"
3
4namespace Editor{
5class Scene {
6  // ...
7  void HandleEvent(const SDL_Event& E) {
8    ActorShelf.HandleEvent(E);
9    TooltipWindow.HandleEvent(E);
10  }
11
12  void Tick(float DeltaTime) {
13    ActorShelf.Tick(DeltaTime);
14    TooltipWindow.Tick(DeltaTime);
15  }
16
17  void Render(SDL_Surface* Surface) {
18    ActorShelf.Render(Surface);
19    TooltipWindow.Render();
20  }
21
22 private:
23  Window& ParentWindow;
24  ActorTooltip TooltipWindow{*this};
25  // ...
26};
27}

Rendering the Actor within the Tooltip

Our tooltip window exists, appears, follows the mouse, and disappears correctly. Now we need to draw the actual actor image inside it. To do this, the ActorTooltip needs access to information from the Actor instance it's currently tracking (DragActor).

Specifically, the tooltip needs:

1. The Image object associated with the actor to render it.
2. The dimensions (w, h) of the actor to size the tooltip window correctly.
3. A way to calculate the offset between where the user clicked on the actor and the actor's top-left corner, for a smoother drag feel.

We'll add getter methods and a new member variable (DragOffset) to the Actor class to provide this information.

src/Editor/Actor.h

1#pragma once
2#include <SDL3/SDL.h>
3#include "Image.h"
4
5namespace Editor {
6class Scene;
7class Actor {
8 public:
9  // ...
10  const SDL_Rect& GetRect() const {
11    return Rect;
12  }
13
14  const SDL_Point& GetDragOffset() const {
15    return DragOffset;
16  }
17
18  const Image& GetArt() const {
19    return Art;
20  }
21
22protected:
23  // ...
24  SDL_Point DragOffset{0, 0};
25};
26}

Using Drag Offset

Our DragOffset value let's us remember exactly where on the actor the user clicked to start dragging. Remembering this position is not technically necessary, but we can use it to improve the user experience.

If we don't store this offset, we can still position the tooltip next to the mouse, but its position will be slightly different to where the user started dragging. Perhaps we'd position the tooltip at the centre of the cursor, or the top left for example. Either way, it's unlikely to match exactly where the user clicked:

But if we remember the drag offset, we can use that value to subtly adjust the position of our tooltip window, creating the effect of the actor "sticking" to the mouse more accurately.

When the user starts dragging our actor, we'll calculate and store their mouse position relative to the top left of our actor's rectangle:

src/Editor/Actor.cpp

1// ...
2
3void Actor::HandleEvent(const SDL_Event& E) {
4  if (
5    E.type == SDL_EVENT_MOUSE_BUTTON_DOWN &&
6    E.button.button == SDL_BUTTON_LEFT &&
7    HasMouseFocus()
8  ) {
9    DragOffset.x = int(E.button.x) - Rect.x;
10    DragOffset.y = int(E.button.y) - Rect.y;
11
12    SDL_Event DragEvent{UserEvents::ACTOR_DRAG};
13    DragEvent.user.data1 = this;
14    SDL_PushEvent(&DragEvent);
15  }
16}

We'll now modify ActorTooltip::PositionWindow() to incorporate the DragOffset. Before setting the window position, we retrieve the offset from the DragActor using its new GetDragOffset() method.

We then subtract the retrieved DragOffsetX and DragOffsetY from the mouse coordinates (x, y) before passing them to SDL_SetWindowPosition(). This adjustment ensures the tooltip window is positioned such that the original click point on the actor aligns with the current mouse cursor, creating the desired "sticky" dragging effect.

src/Editor/ActorTooltip.cpp

1// ...
2
3void ActorTooltip::PositionWindow() {
4  float x, y;
5  SDL_GetMouseState(&x, &y);
6
7  auto [DragOffsetX, DragOffsetY]{
8    DragActor->GetDragOffset()
9  };
10
11  SDL_SetWindowPosition(
12    SDLWindow,
13    int(x) - DragOffsetX,
14    int(y) - DragOffsetY
15  );
16}

Using GetRect()

The tooltip window needs to be the same size as the actor being dragged. When the ACTOR_DRAG event is handled in ActorTooltip::HandleEvent(), right after identifying the DragActor, we can now use its GetRect() method.

We call SDL_SetWindowSize(), passing it the SDLWindow pointer. We extract the width (w) and height (h) from the SDL_Rect returned by DragActor->GetRect() and use these values as the new dimensions for the tooltip window.

This ensures the tooltip perfectly matches the size of the actor image it will display.

src/Editor/ActorTooltip.cpp

1// ...
2
3void ActorTooltip::HandleEvent(
4  const SDL_Event& E) {
5  using namespace UserEvents;
6  if (E.type == ACTOR_DRAG) {
7    DragActor = static_cast<Actor*>(
8      E.user.data1
9    );
10    SDL_SetWindowSize(
11      SDLWindow,
12      DragActor->GetRect().w,
13      DragActor->GetRect().h
14    );
15    SetIsVisible(true);
16  }
17}

Using GetArt()

Finally, our Actor's new GetArt() method lets our tooltip retrieve the Image associated with the actor being dragged. Let's render that image within our tooltip.

Our image should take up the full size of our tooltip's window surface, so we'll render it at position (0, 0) with the width and height provided by the DragActor's GetRect() function.

In our case, that is also the same width and height as the tooltip window itself, as we set its size to these values when our drag event started.

Remember, to see our changes to a window surface, we need to call SDL_UpdateWindowSurface(). In this case, our tooltip is only going to render this image, so we're done. We're not going to be adding anything else to it within this iteration of the application loop, so we can just call SDL_UpdateWindowSurface() as the last step of our Render() function.

src/Editor/ActorTooltip.cpp

1// ...
2
3void ActorTooltip::Render() {
4  if (!isVisible) return;
5  DragActor->GetArt().Render(
6    GetSurface(),
7    SDL_Rect{
8      0, 0,
9      DragActor->GetRect().w,
10      DragActor->GetRect().h
11    });
12
13  SDL_UpdateWindowSurface(SDLWindow);
14}

Running our program, we should now see that we can click and drag actors from our menu, and even drag them outside of our window:

Complete Code

Complete versions of the files we updated are provided below:

Files

src

Select a file to view its content

Summary

This lesson focused on making the ActorMenu interactive by adding drag capabilities. We enabled users to click on an actor, triggering a visual feedback mechanism.

The core components added were a custom ACTOR_DRAG event and the ActorTooltip class. The Actor now detects clicks and pushes this event, carrying a pointer to itself.

The ActorTooltip listens for this event, creates a borderless, always-on-top window, sizes it appropriately, and displays the dragged actor's image. This tooltip window dynamically follows the mouse cursor until the mouse button is released.

We reviewed how to:

• Define custom events for application-specific signaling.
• Use SDL_WindowFlags to create specialized windows (tooltips).
• Manage window visibility and position dynamically.
• Render content to a secondary window surface and update it.
• Implement a drag offset for a more natural user experience.

In the next lesson, we'll handle the "drop" part of the interaction. We'll learn how to detect where the user releases the mouse, verify if it's a valid drop location, and then instantiate a new actor at that position in our level.