Creating SDL2 Buttons

Here's the code from our previous lessons that we'll use as a starting point. We have classes for managing the window, a simple UI layer, and a Rectangle component:

Let's start by creating a simple Button class to manage our buttons. Similar to our Rectangle class, we'll have a constructor that receives an SDL_Rect to control the size and position, which we'll use later.

We'll also add HandleEvent() and Render() functions so we can connect Button instances to our application architecture:

1// Button.h
2#pragma once
3#include <SDL.h>
4
5class Button {
6 public:
7  Button(const SDL_Rect& R) {
8    // ...
9  }
10  
11  void HandleEvent(SDL_Event& E) {
12    // ...
13  }
14
15  void Render(SDL_Surface* Surface) {
16    // ...
17  }
18};

Let's add a Button instance to our UI class:

1// UI.h
2#pragma once
3#include <SDL.h>
4#include "Rectangle.h"
5#include "Button.h"
6
7class UI {
8public:
9  void Render(SDL_Surface* Surface) const {
10    A.Render(Surface);
11    B.Render(Surface);
12    C.Render(Surface);
13  }
14
15  void HandleEvent(SDL_Event& E) {
16    A.HandleEvent(E);
17    B.HandleEvent(E);
18    C.HandleEvent(E);
19  }
20
21private:
22  Rectangle A{{50, 50, 50, 50}};
23  Rectangle B{{150, 50, 50, 50}};
24  Button C{{250, 50, 50, 50}};
25};

Our Button class is likely to find a lot of the code we added to our Rectangle class helpful. This includes rendering a rectangle to act as the background color of our button, and detecting when the mouse enters or clicks in this area.

To take advantage of the code we've already written in our Rectangle class, there are two main approaches we might consider for our Button. First, we could add a Rectangle member to our Button class. That might look something like this:

1// Button.h
2#pragma once
3#include <SDL.h>
4#include "Rectangle.h"
5
6class Button {
7public:
8  Button(const SDL_Rect& Rect)
9  : Rect{Rect}
10  {
11    Rect.SetColor({255, 165, 0, 255}); // Orange
12  }
13  
14  void HandleEvent(SDL_Event& E) {
15    Rect.HandleEvent(E);
16    // Implement button-specific event logic...
17  }
18
19  void Render(SDL_Surface* Surface) {
20    Rect.Render(Surface);
21    // Render the rest of the button...
22  }
23
24private:
25  Rectangle Rect;
26};

Alternatively, we could inherit from Rectangle, thereby making Rectangle a base class of our Button. That could look like this:

1// Button.h
2#pragma once
3#include <SDL.h>
4#include "Rectangle.h"
5
6class Button : public Rectangle {
7 public:
8  Button(const SDL_Rect& Rect)
9  : Rectangle{Rect}
10  {
11    SetColor({255, 165, 0, 255}); // Orange
12  }
13  
14  void HandleEvent(SDL_Event& E) override {
15    Rectangle::HandleEvent(E);
16    // Implement button-specific event logic...
17  }
18
19  void Render(SDL_Surface* Surface) override {
20    Rectangle::Render(Surface);
21    // Render the rest of the button...
22  }
23};

In general, the way to think about this is to wonder whether it is more accurate to say that a Button has a Rectangle (option 1) or that a Button is a Rectangle (option 2).

Sometimes, this will be an obvious distinction - a Car has an Engine, but it is a Vehicle. So it would inherit from Vehicle, but contain an Engine as a member variable.

In the Button and Rectangle case, either approach is reasonable. We'll go with inheritance in this lesson, but only because it offers more learning opportunities.

When a class like our Rectangle is intended to be inherited from, we should spend some time thinking about how we can design our class to best support this.

For example, what behaviours are derived classes likely to want to override? It seems likely that derived classes may want to react to things like the user clicking the rectangle, or the mouse entering and exiting its bounds.

Unfortunately, with our current Rectangle design, it's not particularly clear it expects its derived classes like Button to do this. For example, implementing a reaction to the cursor leaving the bounds of the rectangle might look something like this, which is not exactly intuitive:

1// Button.h
2#pragma once
3#include <SDL.h>
4#include "Rectangle.h"
5
6class Button : public Rectangle {
7 public:
8  Button(const SDL_Rect& Rect)
9  : Rectangle{Rect}
10  {
11    SetColor({255, 165, 0, 255}); // Orange
12  }
13
14  void HandleEvent(SDL_Event& E) {
15    // Was the pointer hovering over the button
16    // before the event has handled?
17    bool wasPointerHovering{isPointerHovering};
18
19    // Handle the event by deferring to the
20    // base implementation
21    Rectangle::HandleEvent(E);
22
23    // Has that event changed the
24    // isPointerHovering value?
25    if (!wasPointerHovering && isPointerHovering) {
26      std::cout << "Hello mouse\n";
27    }
28  }
29};

Note: this change would also require isPointerHovering to be moved from private to protected within Rectangle.

To design a better API, a good strategy is to approach things in the opposite order. That is, write the code you'd ideally like to write, whilst pretending the API supports it. That might look something like this:

1// Button.h
2// ...
3
4class Button : public Rectangle {
5public:
6  // ...
7  
8  // This doesn't exist, but I wish it did
9  void OnMouseEnter() override {
10    std::cout << "Hello mouse\n";
11  }
12};

Then, write the underlying code that makes the API work that way. In this case, that requires us to update the Rectangle base class:

1// Rectangle.h
2#pragma once
3#include <SDL.h>
4
5class Rectangle {
6 public:
7  // ...
8
9  virtual void OnMouseEnter() {}
10
11  void HandleEvent(SDL_Event& E) {
12    if (E.type == SDL_MOUSEMOTION) {
13      bool wasPointerHovering{isPointerHovering};
14      isPointerHovering = isWithinRect(
15        E.motion.x, E.motion.y
16      );
17      if (!wasPointerHovering && isPointerHovering) {
18        OnMouseEnter();
19      }
20    } else if (
21      E.type == SDL_WINDOWEVENT &&
22      E.window.event == SDL_WINDOWEVENT_LEAVE
23    ) {
24      isPointerHovering = false;
25    } else if (E.type == SDL_MOUSEBUTTONDOWN) {
26      if (isPointerHovering &&
27        E.button.button == SDL_BUTTON_LEFT
28      ) {
29        std::cout << "A left-click happened "
30          "on me!\n";
31      }
32    }
33  }
34  // ...
35};

Let's add support for OnMouseExit() and OnLeftClick(), too:

1// Rectangle.h
2#pragma once
3#include <SDL.h>
4
5class Rectangle {
6 public:
7  // ...
8  
9  virtual void OnMouseEnter() {}
10  virtual void OnMouseExit() {}
11  virtual void OnLeftClick() {}
12
13  void HandleEvent(SDL_Event& E) {
14    if (E.type == SDL_MOUSEMOTION) {
15      bool wasPointerHovering{isPointerHovering};
16      isPointerHovering = isWithinRect(
17        E.motion.x, E.motion.y
18      );
19      if (!wasPointerHovering && isPointerHovering) {
20        OnMouseEnter();
21      } else if (
22        wasPointerHovering && !isPointerHovering
23      ) {
24        OnMouseExit();
25      }
26    } else if (
27      E.type == SDL_WINDOWEVENT &&
28      E.window.event == SDL_WINDOWEVENT_LEAVE
29    ) {
30      if (isPointerHovering) OnMouseExit();
31      isPointerHovering = false;
32    } else if (E.type == SDL_MOUSEBUTTONDOWN) {
33      if (isPointerHovering &&
34        E.button.button == SDL_BUTTON_LEFT
35      ) {
36        std::cout << "A left-click happened "
37          "on me!\n";
38        OnLeftClick();
39      }
40    }
41  }
42
43  // ...
44};

This makes implementing behaviours in derived classes significantly easier and less error-prone:

1// Button.h
2#pragma once
3#include <SDL.h>
4#include "Rectangle.h"
5
6class Button : public Rectangle {
7 public:
8  Button(const SDL_Rect& Rect)
9  : Rectangle{Rect}
10  {
11    SetColor({255, 165, 0, 255});
12  }
13
14  void OnMouseEnter() override {
15    std::cout << "Hello mouse\n";
16  }
17
18  void OnMouseExit() override {
19    std::cout << "Goodbye mouse\n";
20  }
21
22  void OnLeftClick() override {
23    std::cout << "You left-clicked me!\n";
24  }
25};

1Hello mouse
2You left-clicked me!
3Goodbye mouse

Having our HandleEvent() function change some state on the component that received the event is fairly straightforward - we just update variables or call some function as normal. Below, our Button objects become red when left-clicked:

1// Button.h
2// ...
3
4class Button : public Rectangle {
5 public:
6  void OnLeftClick() override {
7    SetColor({255, 0, 0, 255});
8  }
9};

However, in more complex programs, a component in one area of the program will need to influence the behaviour in some other area.

We'll cover the four most common examples of this:

• Communicating with a child or children - for example, a UI talking to the Rectangles that it manages
• Communicating with a parent - for example, a Button talking to the UI that manages it
• Communicating with an arbitrary component - for example, a Button talking to a Rectangle that it has no obvious relationship to
• Communicating with everything - for example, a Button telling every other component that something important has happened

Having a component communicate with a child tends to be quite easy, as the child is a member variable, or within a container (such as a std::vector) that is a member variable.

As such, we can simply manipulate children through their public members:

1// UI.h
2// ...
3
4class UI {
5public:
6  // ...
7
8  void SetRectangleColors(const SDL_Color& Color) {
9    A.SetColor(Color);
10    B.SetColor(Color);
11  }
12  
13  // ...
14};

To communicate with a parent, a component needs a pointer or reference to that parent. Let's update our Button class so that each button knows which UI object is its parent.

A common approach is to simply have the component accept a constructor argument containing that reference, and store it as a member variable. We then have the parent provide a reference to itself as that argument when it creates its child.

So, in this case, our Button class will store a reference to a UI object.

Because our UI.h header file is already including our Button.h header file, we can't have our Button.h also include UI.h. This would result in a circular dependency.

Instead, let's just forward-declare our UI as a class. This gives the compiler enough information to know that UI is the name of a type, so we can use it in our constructor argument list and as the type for a new UIManager variable:

1// Button.h
2#pragma once
3#include <SDL.h>
4#include "Rectangle.h"
5
6class UI;
7
8class Button : public Rectangle {
9 public:
10  Button(UI& UIManager, const SDL_Rect& Rect)
11  : UIManager{UIManager},
12    Rectangle{Rect}
13  {
14    SetColor({255, 165, 0, 255});
15  }
16
17private:
18  UI& UIManager;
19};

Back in the UI class, we'll provide this reference to our Button through the this pointer:

1// UI.h
2// ...
3
4class UI {
5  // ...
6
7private:
8  // ...
9  Button C{*this, {250, 50, 50, 50}};
10};

When our button is left-clicked, let's have it call the SetRectangleColors() method on it's parent UI. This requires us to override the OnLeftClick() function we inherited from our Rectangle base class.

However, because we have only forward-declared the UI type in Button.h, it will be an incomplete type. This limits what the Button.h header file can do with our UIManager. For example, we won't be able to call UI functions from our Button header file.

To solve this, we'll need to add a new source file to our project, where we can fully define the required Button::OnLeftClick() behaviour. However, let's first declare this override in the header file:

1// Button.h
2// ...
3
4class Button : public Rectangle {
5 public:
6  // ...
7
8  void OnLeftClick() override;
9
10  // ...
11};

Let's add a new Button.cpp source file to our project, which can safely include both the Button and UI header files:

1// Button.cpp
2#include "Button.h"
3#include "UI.h"
4
5void Button::OnLeftClick() {
6  UIManager.SetRectangleColors(
7    {0, 255, 0, 255} // Green
8  );
9}

With those changes, clicking our button should now call the SetRectangleColors() method on its UI parent, and that UI should then call SetColor() on each of it's Rectangle children:

Communicating with a random component elsewhere in the hierarchy is conceptually similar to communicating with a parent. We just need some way to acquire a reference or pointer to that object. In this example, our Button receives a Rectangle reference as a constructor argument and, when the Button is clicked, it turns that rectangle green:

1// Button.h
2// ...
3
4class Button : public Rectangle {
5 public:
6  Button(
7    UI& UIManager,
8    const SDL_Rect& Rect,
9    Rectangle& Target
10  )
11  : Rectangle{Rect},
12    UIManager{UIManager},
13    Target{Target}
14  {
15    SetColor({255, 165, 0, 255});
16  }
17
18  void OnLeftClick() override {
19    Target.SetColor({0, 255, 0, 255});
20  };
21
22private:
23  Rectangle& Target;
24  UI& UIManager;
25};

It's generally going to be our manager-style classes like UI that establish these links between components:

1// UI.h
2// ...
3
4class UI {
5  // ...
6
7private:
8  Rectangle A{{50, 50, 50, 50}};
9  Rectangle B{{150, 50, 50, 50}};
10  Button C{*this , {250, 50, 50, 50}, A};
11};

With these changes, clicking our button now turns the A rectangle green:

The last and most impactful way that a component can communicate with other components of our program is to push an event onto the main event queue. This is because we're not limited to just reading events from the event queue, we can also write to it.

A component from anywhere in our hierarchy can push an SDL_Event. That data shows up in the event loop in our main() function, like any other event. From there, the message gets sent to every other component, through the HandleEvent() pattern we're starting to establish:

Our next lesson is dedicated to this topic but, as a quick preview, here is how we can make our Button quit the application by pushing an SDL_QUIT event, which our application loop over in main.cpp is already set up to react to:

1// Button.cpp
2#include "Button.h"
3
4void Button::OnLeftClick() {
5  SDL_Event E{SDL_QUIT};
6  SDL_PushEvent(&E);
7}

Here is the complete code incorporating all the changes we made throughout this lesson, including the new Button class and the modifications to Rectangle and UI.

In this lesson, we created an interactive Button class by inheriting from our Rectangle class and using virtual functions for event handling. We explored various patterns for communication between different components in our application, from direct parent/child interaction to using the main SDL event queue.

Key Takeaways:

• Buttons can be built by extending existing shape classes.
• Virtual functions - OnMouseEnter(), OnMouseExit(), and OnLeftClick() - provide a clean API for derived classes to customize behavior.
• Inheritance (Button is a Rectangle) and Composition (Button has a Rectangle) are two ways to reuse code.
• Components can communicate via direct references (parent-child, child-parent, arbitrary) or indirectly via the event queue using SDL_PushEvent().
• Forward declarations and separate .cpp files help manage dependencies and incomplete types.