ui/platform_window/extensions/README

This directory provides extensions of platform APIs that PlatformWindow
implementations can use to add support for more advanced APIs their
platform provides.

The sole intent of the extensions is to avoid casting from a PlatfromWindow
to the extensions and avoid polluting the PlatformWindow APIs with
unrelated methods.

In order to let clients to access APIs of the extensions that an
implementation of a PlatformWindow may have, one must set the
extension as a property of the PlatformWindow. Then, the client can
access the extension by providing the pointer to the PlatformWindow
to corresponding GetMyExtension() global method that will check
the properties of the PlatformWindow and return a pointer to the
extension if such a property exists.

For example,

class MyExtension {
 public:
   virtual void MyExtensionMethod1() = 0;
   virtual void MyExtensionMethod2() = 0;

 protected:
   virtual ~MyExtension();
   void SetMyExtension(PlatformWindow* window, MyExtension* extension);
};

DEFINE_UI_CLASS_PROPERTY_TYPE(MyExtension*)
DEFINE_UI_CLASS_PROPERTY_KEY(MyExtension*,
                             kMyExtensionKey,
                             nullptr)

MyExtensions::~MyExtension() = default;

void MyExtension::SetMyExtension(PlatformWindow* window, MyExtension* extension) {
     window->SetProperty(kMyExtensionKey, extension);
}

MyExtension* GetMyExtension(const PlatformWindow& window) {
  return window.GetProperty(kMyExtensionKey);
}

-------------------------------------------------------------------------------

class MyWindow : public PlatformWindow,
                 public MyExtension {
 public:
  MyWindow() {
    // Sets the MyExtension property of the PlatformWindow.
    // Cast to MyExtension for a better readibility.
    SetMyExtension(this, static_cast<MyExtension*>(this));
  }

  // PlatformWindow overrides:
  void Method1() override {}
  void Method2() override {}

  // MyExtension overrides:
  void MyExtensionMethod1() override {}
  void MyExtensionMethod2() override {}
};

-------------------------------------------------------------------------------

class Client {
 public:
  void CreatePlatformWindow() {
    auto window = std::make_unique<MyWindow>();
    auto* extension = GetMyExtension(*window.get());
  }
};