Window: visual effects that say what they did, and one meaning for a hidden title bar

SetVisualEffect returns whether the effect is in force, IsVisualEffectSupported
answers beforehand, and GetVisualEffect reads the effect off the native window
instead of off whichever wrapper was asked; Linux, Android, iOS and OpenHarmony
say no rather than recording a value they cannot honour. MicaAlt, Hud, Popover
and Menu are new.

macOS: the effect view sits below a FlutterView's own layers, the Flutter view
controller is left clear for as long as the effect lasts, and the window's
background colour and opacity are no longer overwritten on the way.

Windows: every effect now works on Windows 10 as a blur-behind kind, where all
of them used to need Windows 11 22H2 and do nothing at all below it; on 22H2
they are system backdrops, which cover the title bar too. A window of the
library's own class also keeps its own background colour instead of sharing one
class brush with every other window.

TitleBarStyle::Hidden means the bare window on all six platforms now - no title
bar and no window control buttons - where macOS used to keep the traffic lights
on a transparent bar and the style reset their visibility as a side effect. The
transparent bar macOS gave for free became a property of its own:
SetContentUnderTitleBar() takes the title bar into the content area and leaves
it an overlay with the buttons still on it, which is what a window whose
background runs to the top edge wants. IsContentUnderTitleBarSupported() answers
for the platform, and only macOS says yes: on Windows the caption buttons DWM
keeps drawing answer HTCLIENT once the client area takes the caption band, so
they would have to be drawn and hit-tested by hand, and on Linux a GTK header
bar is a sibling above the content rather than an overlay over it.

window_visual_effect_example walks a window through every effect and checks what
the API reports about it.

Author: lijy91

CMakeLists.txt

@@ -35,6 +35,7 @@ add_subdirectory(examples/window_drag_session_example)
 add_subdirectory(examples/window_lifecycle_example)
 add_subdirectory(examples/window_parent_example)
 add_subdirectory(examples/window_shadow_example)
+add_subdirectory(examples/window_visual_effect_example)
 add_subdirectory(examples/drag_drop_example)
 add_subdirectory(examples/desktop_features_example)
 

examples/window_visual_effect_example/CMakeLists.txt

@@ -0,0 +1,28 @@
+cmake_minimum_required(VERSION 3.10)
+
+project(window_visual_effect_example VERSION 0.0.1 LANGUAGES CXX)
+
+# Set C++ standard
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# Add example program
+add_executable(window_visual_effect_example
+  "main.cpp"
+)
+
+# Link main library
+target_link_libraries(window_visual_effect_example PRIVATE nativeapi)
+
+# Set example program properties
+set_target_properties(window_visual_effect_example PROPERTIES
+  OUTPUT_NAME "window_visual_effect_example"
+)
+
+# Set example program compile options (macOS only)
+if(APPLE)
+    set_source_files_properties("main.cpp"
+    PROPERTIES
+    COMPILE_FLAGS "-x objective-c++"
+  )
+endif()

examples/window_visual_effect_example/main.cpp

@@ -0,0 +1,115 @@
+#include <chrono>
+#include <cstdlib>
+#include <functional>
+#include <iostream>
+#include <string>
+#include <thread>
+#include <utility>
+#include <vector>
+
+#include "nativeapi.h"
+
+using nativeapi::Color;
+using nativeapi::VisualEffect;
+using nativeapi::Window;
+
+// Walks a window through every VisualEffect, over a plain red window that gives the
+// effects something to show. What the API reports is checked here - the exit code is the
+// number of expectations that did not hold - and each step prints a "STEP" line once it is
+// on screen, so that whoever watches (tools/gui has a test that does) knows when to look.
+//
+// It drives the windows itself and needs no input.
+int main() {
+  nativeapi::SetMainThread();
+
+  int failures = 0;
+  auto expect = [&](const std::string& what, bool ok) {
+    std::cout << (ok ? "PASS " : "FAIL ") << what << std::endl;
+    if (!ok) {
+      failures++;
+    }
+  };
+
+  const std::vector<std::pair<VisualEffect, std::string>> effects = {
+      {VisualEffect::Blur, "Blur"},       {VisualEffect::Acrylic, "Acrylic"},
+      {VisualEffect::Hud, "Hud"},         {VisualEffect::Popover, "Popover"},
+      {VisualEffect::Menu, "Menu"},       {VisualEffect::Mica, "Mica"},
+      {VisualEffect::MicaAlt, "MicaAlt"},
+  };
+
+  std::shared_ptr<Window> backdrop;
+  std::shared_ptr<Window> window;
+  VisualEffect in_force = VisualEffect::None;
+
+  std::vector<std::function<void()>> steps = {[&] {
+    backdrop = std::make_shared<Window>();
+    backdrop->SetTitle("Backdrop");
+    backdrop->SetBackgroundColor(Color::FromRGBA(255, 0, 0));
+    backdrop->SetContentSize({560, 420});
+    backdrop->SetPosition({200, 160});
+    backdrop->Show();
+
+    window = std::make_shared<Window>();
+    window->SetTitle("Visual effect");
+    window->SetContentSize({400, 260});
+    window->SetPosition({280, 240});
+    // A child stays above its parent, whichever of the two is brought forward.
+    window->SetParentWindow(backdrop);
+    window->Show();
+    window->Focus();
+    expect("a window starts without a visual effect",
+           window->GetVisualEffect() == VisualEffect::None);
+    expect("no effect is supported everywhere",
+           Window::IsVisualEffectSupported(VisualEffect::None));
+    std::cout << "STEP None applied" << std::endl;
+  }};
+
+  for (const auto& [effect, name] : effects) {
+    steps.push_back([&, effect = effect, name = name] {
+      const bool supported = Window::IsVisualEffectSupported(effect);
+      const bool applied = window->SetVisualEffect(effect);
+      expect(name + ": SetVisualEffect agrees with IsVisualEffectSupported", applied == supported);
+      if (applied) {
+        in_force = effect;
+      }
+      expect(name + ": GetVisualEffect is the effect in force",
+             window->GetVisualEffect() == in_force);
+      std::cout << "STEP " << name << (applied ? " applied" : " refused") << std::endl;
+    });
+  }
+
+  steps.push_back([&] {
+    // A background color given while an effect is active waits for the effect to go.
+    window->SetBackgroundColor(Color::FromRGBA(0, 0, 255));
+    expect("the background color is kept while an effect is active",
+           window->GetBackgroundColor().b == 255 && window->GetBackgroundColor().r == 0);
+    std::cout << "STEP Background " << (in_force == VisualEffect::None ? "shown" : "waiting")
+              << std::endl;
+  });
+  steps.push_back([&] {
+    expect("the effect can be removed", window->SetVisualEffect(VisualEffect::None));
+    expect("no effect is in force afterwards", window->GetVisualEffect() == VisualEffect::None);
+    std::cout << "STEP Removed applied" << std::endl;
+  });
+  steps.push_back([&] {
+    std::cout << (failures == 0 ? "ALL PASS" : "FAILED") << std::endl;
+    // Not Quit(): how a platform's loop ends must not decide the exit code.
+    std::cout.flush();
+    std::_Exit(failures);
+  });
+
+  std::thread driver([&] {
+    for (size_t i = 0; i < steps.size(); i++) {
+      // The windows stay as they first come up for a while: a watcher has to find them.
+      std::this_thread::sleep_for(std::chrono::milliseconds(i == 1 ? 6000 : 2500));
+      nativeapi::RunOnMainThread(steps[i]);
+    }
+  });
+  driver.detach();
+
+  // On Windows destroying any window of the library ends the loop (its window
+  // procedure posts WM_QUIT), so enter it again: the last step ends the process.
+  while (true) {
+    nativeapi::Application::GetInstance().Run();
+  }
+}

src/capi/window_c.cpp

@@ -894,6 +894,41 @@ native_title_bar_style_t native_window_get_title_bar_style(native_window_t windo
   }
 }
 
+bool native_window_set_content_under_title_bar(native_window_t window, bool is_content_under_title_bar) {
+  auto self = nativeapi::HandleTable::GetInstance().Resolve<nativeapi::Window>(window);
+  if (!self) {
+    return false;
+  }
+  try {
+    return self->SetContentUnderTitleBar(is_content_under_title_bar);
+  } catch (...) {
+    fprintf(stderr, "[nativeapi] %s: unexpected exception\n", "native_window_set_content_under_title_bar");
+    return false;
+  }
+}
+
+bool native_window_is_content_under_title_bar(native_window_t window) {
+  auto self = nativeapi::HandleTable::GetInstance().Resolve<nativeapi::Window>(window);
+  if (!self) {
+    return false;
+  }
+  try {
+    return self->IsContentUnderTitleBar();
+  } catch (...) {
+    fprintf(stderr, "[nativeapi] %s: unexpected exception\n", "native_window_is_content_under_title_bar");
+    return false;
+  }
+}
+
+bool native_window_is_content_under_title_bar_supported(void) {
+  try {
+    return nativeapi::Window::IsContentUnderTitleBarSupported();
+  } catch (...) {
+    fprintf(stderr, "[nativeapi] %s: unexpected exception\n", "native_window_is_content_under_title_bar_supported");
+    return false;
+  }
+}
+
 void native_window_set_has_shadow(native_window_t window, bool has_shadow) {
   auto self = nativeapi::HandleTable::GetInstance().Resolve<nativeapi::Window>(window);
   if (!self) {
@@ -948,17 +983,16 @@ float native_window_get_opacity(native_window_t window) {
   }
 }
 
-void native_window_set_visual_effect(native_window_t window, native_visual_effect_t effect) {
+bool native_window_set_visual_effect(native_window_t window, native_visual_effect_t effect) {
   auto self = nativeapi::HandleTable::GetInstance().Resolve<nativeapi::Window>(window);
   if (!self) {
-    return;
+    return false;
   }
   try {
-    self->SetVisualEffect(to_cpp_visual_effect(effect));
-    return;
+    return self->SetVisualEffect(to_cpp_visual_effect(effect));
   } catch (...) {
     fprintf(stderr, "[nativeapi] %s: unexpected exception\n", "native_window_set_visual_effect");
-    return;
+    return false;
   }
 }
 
@@ -975,6 +1009,15 @@ native_visual_effect_t native_window_get_visual_effect(native_window_t window) {
   }
 }
 
+bool native_window_is_visual_effect_supported(native_visual_effect_t effect) {
+  try {
+    return nativeapi::Window::IsVisualEffectSupported(to_cpp_visual_effect(effect));
+  } catch (...) {
+    fprintf(stderr, "[nativeapi] %s: unexpected exception\n", "native_window_is_visual_effect_supported");
+    return false;
+  }
+}
+
 void native_window_set_background_color(native_window_t window, native_color_t color) {
   auto self = nativeapi::HandleTable::GetInstance().Resolve<nativeapi::Window>(window);
   if (!self) {

src/capi/window_c.h

@@ -32,6 +32,10 @@ typedef enum {
   NATIVE_VISUAL_EFFECT_BLUR = 1,
   NATIVE_VISUAL_EFFECT_ACRYLIC = 2,
   NATIVE_VISUAL_EFFECT_MICA = 3,
+  NATIVE_VISUAL_EFFECT_MICA_ALT = 4,
+  NATIVE_VISUAL_EFFECT_HUD = 5,
+  NATIVE_VISUAL_EFFECT_POPOVER = 6,
+  NATIVE_VISUAL_EFFECT_MENU = 7,
 } native_visual_effect_t;
 
 typedef enum {
@@ -287,6 +291,15 @@ void native_window_set_title_bar_style(native_window_t window, native_title_bar_
 FFI_PLUGIN_EXPORT
 native_title_bar_style_t native_window_get_title_bar_style(native_window_t window);
 
+FFI_PLUGIN_EXPORT
+bool native_window_set_content_under_title_bar(native_window_t window, bool is_content_under_title_bar);
+
+FFI_PLUGIN_EXPORT
+bool native_window_is_content_under_title_bar(native_window_t window);
+
+FFI_PLUGIN_EXPORT
+bool native_window_is_content_under_title_bar_supported(void);
+
 FFI_PLUGIN_EXPORT
 void native_window_set_has_shadow(native_window_t window, bool has_shadow);
 
@@ -300,11 +313,14 @@ FFI_PLUGIN_EXPORT
 float native_window_get_opacity(native_window_t window);
 
 FFI_PLUGIN_EXPORT
-void native_window_set_visual_effect(native_window_t window, native_visual_effect_t effect);
+bool native_window_set_visual_effect(native_window_t window, native_visual_effect_t effect);
 
 FFI_PLUGIN_EXPORT
 native_visual_effect_t native_window_get_visual_effect(native_window_t window);
 
+FFI_PLUGIN_EXPORT
+bool native_window_is_visual_effect_supported(native_visual_effect_t effect);
+
 FFI_PLUGIN_EXPORT
 void native_window_set_background_color(native_window_t window, native_color_t color);
 
@@ -420,6 +436,14 @@ inline native_visual_effect_t to_c_visual_effect(nativeapi::VisualEffect value)
       return NATIVE_VISUAL_EFFECT_ACRYLIC;
     case nativeapi::VisualEffect::Mica:
       return NATIVE_VISUAL_EFFECT_MICA;
+    case nativeapi::VisualEffect::MicaAlt:
+      return NATIVE_VISUAL_EFFECT_MICA_ALT;
+    case nativeapi::VisualEffect::Hud:
+      return NATIVE_VISUAL_EFFECT_HUD;
+    case nativeapi::VisualEffect::Popover:
+      return NATIVE_VISUAL_EFFECT_POPOVER;
+    case nativeapi::VisualEffect::Menu:
+      return NATIVE_VISUAL_EFFECT_MENU;
     default:
       return NATIVE_VISUAL_EFFECT_NONE;
   }
@@ -435,6 +459,14 @@ inline nativeapi::VisualEffect to_cpp_visual_effect(native_visual_effect_t value
       return nativeapi::VisualEffect::Acrylic;
     case NATIVE_VISUAL_EFFECT_MICA:
       return nativeapi::VisualEffect::Mica;
+    case NATIVE_VISUAL_EFFECT_MICA_ALT:
+      return nativeapi::VisualEffect::MicaAlt;
+    case NATIVE_VISUAL_EFFECT_HUD:
+      return nativeapi::VisualEffect::Hud;
+    case NATIVE_VISUAL_EFFECT_POPOVER:
+      return nativeapi::VisualEffect::Popover;
+    case NATIVE_VISUAL_EFFECT_MENU:
+      return nativeapi::VisualEffect::Menu;
     default:
       return nativeapi::VisualEffect::None;
   }

src/platform/android/window_android.cpp

@@ -14,9 +14,8 @@ namespace nativeapi {
 // Private implementation class
 class Window::Impl {
  public:
-  Impl(ANativeWindow* window) : native_window_(window), visual_effect_(VisualEffect::None) {}
+  Impl(ANativeWindow* window) : native_window_(window) {}
   ANativeWindow* native_window_;
-  VisualEffect visual_effect_;
 };
 
 Window::Window() : pimpl_(std::make_unique<Impl>(nullptr)) {}
@@ -343,6 +342,18 @@ TitleBarStyle Window::GetTitleBarStyle() const {
   return TitleBarStyle::Normal;
 }
 
+bool Window::SetContentUnderTitleBar(bool is_content_under_title_bar) {
+  return false;
+}
+
+bool Window::IsContentUnderTitleBar() const {
+  return false;
+}
+
+bool Window::IsContentUnderTitleBarSupported() {
+  return false;
+}
+
 void Window::SetHasShadow(bool has_shadow) {
   ALOGW("SetHasShadow not supported on Android");
 }
@@ -359,13 +370,16 @@ float Window::GetOpacity() const {
   return 1.0f;
 }
 
-void Window::SetVisualEffect(VisualEffect effect) {
-  pimpl_->visual_effect_ = effect;
-  ALOGW("SetVisualEffect not supported on Android");
+bool Window::SetVisualEffect(VisualEffect effect) {
+  return effect == VisualEffect::None;
 }
 
 VisualEffect Window::GetVisualEffect() const {
-  return pimpl_->visual_effect_;
+  return VisualEffect::None;
+}
+
+bool Window::IsVisualEffectSupported(VisualEffect effect) {
+  return effect == VisualEffect::None;
 }
 
 void Window::SetBackgroundColor(const Color& color) {