Understanding Incomplete Types in C++ Forward Declarations

When we forward-declare a class, like we did with class UI; in Button.h, we're telling the compiler, "Trust me, there's a class named UI defined somewhere else."

1// Button.h
2#pragma once
3#include <SDL.h>
4#include "Rectangle.h"
5
6class UI; // Forward declaration
7
8class Button : public Rectangle {
9 public:
10  // ...
11  // We can USE the name UI here:
12  Button(UI& UIManager, const SDL_Rect& Rect);
13private:
14  // We can declare members of this type:
15  UI& UIManager;
16};

At this point, inside Button.h, UI is considered an incomplete type. The compiler knows the name UI refers to a class type, but it doesn't know anything else about it:

• It doesn't know how big UI is (its size in memory).
• It doesn't know what member variables UI has.
• It doesn't know what member functions UI has.

What Can You Do with an Incomplete Type?

Because the compiler lacks detailed information, there are limitations on what you can do with an incomplete type directly within the header file that only sees the forward declaration:

• You cannot create an instance of UI (e.g., UI myUI;). The compiler needs to know the size.
• You cannot use sizeof(UI).
• You cannot access members of UI (e.g., UIManager.someMember). The compiler doesn't know if someMember exists.
• You cannot call methods of UI (e.g., UIManager.SomeFunction()). The compiler doesn't know if SomeFunction exists or what its signature is.
• You cannot inherit from UI.
• You cannot use it as a base type for dynamic_cast.

However, you can do things that don't require knowing the class's internal details:

• You can declare pointers or references to UI (e.g., UI* ptr; or UI& ref;). Pointers and references usually have a fixed size regardless of the type they point/refer to.
• You can declare functions or methods that take or return pointers or references to UI (e.g., void ProcessUI(UI* uiPtr); or UI& GetUIManager();).

Why It Prevents Calling Functions in Headers

In our lesson, the Button class needed to call the SetRectangleColors() method on its UIManager reference.

1// Button.h - Trying to DEFINE OnLeftClick here
2// ...
3class Button : public Rectangle {
4 public:
5  Button(UI& UIManager, const SDL_Rect& Rect);
6
7  // Attempting definition in the header:
8  void OnLeftClick() override {
9    // ERROR! UI is an incomplete type here!
10    UIManager.SetRectangleColors({0,255,0,255}); 
11  }
12private:
13  UI& UIManager;
14};

This fails because when the compiler processes Button.h, it only sees class UI;. It has no idea if UI actually has a method called SetRectangleColors or what arguments it takes.

The Solution: Move Definition to .cpp

The solution is to only declare the function in the header and define it in a corresponding source file (.cpp).

1// Button.h - Declaration Only
2// ...
3class Button : public Rectangle {
4 public:
5  Button(UI& UIManager, const SDL_Rect& Rect);
6  void OnLeftClick() override; // Declaration 
7private:
8  UI& UIManager;
9};

1// Button.cpp - Definition
2#include "Button.h"
3#include "UI.h" // Include the full definition! 
4
5void Button::OnLeftClick() {
6  // OK! Compiler now sees the full definition
7  // of UI from UI.h and knows about the method.
8  UIManager.SetRectangleColors(
9    {0, 255, 0, 255} // Green
10  );
11}

In Button.cpp, we #include "UI.h". This gives the compiler the full definition of the UI class before it compiles the Button::OnLeftClick method. Now, UI is a complete type, and the compiler can verify that SetRectangleColors exists and is being called correctly.

Forward declarations and incomplete types are essential tools for breaking circular dependencies between headers and reducing compilation times, but they require us to separate declarations (in .h) from definitions that require complete types (in .cpp).