add wezterm.gui.get_appearance to retrieve dark mode

This simplifies the "change scheme based on dark mode" example
a lot.  This was previously impossible to do because we didn't
have a lua module associated with the gui until recently, so
the only way to reference a gui-related object was via an
event callback.

refs: https://github.com/wez/wezterm/issues/2258

docs/changelog.md

@@ -21,6 +21,7 @@ As features stabilize some brief notes about them will accumulate here.
 * New [wezterm.color](config/lua/wezterm.color/index.md) module for working with colors.
 * New [wezterm.gui](config/lua/wezterm.gui/index.md) module and [mux_window:gui_window](config/lua/mux-window/gui_window.md) method.
 * New [wezterm.gui.screens()](config/lua/wezterm.gui/screens.md) function for getting information about the available screens/monitors/displays
+* New [wezterm.gui.get_appearance()](config/lua/wezterm.gui/get_appearance.md) function for a simpler way to get system dark mode state
 * You may now use [wezterm.format](config/lua/wezterm/format.md) (or otherwise use strings with escape sequences) in the labels of the [Launcher Menu](config/launch.md#the-launcher-menu).
 * You may now specify `assume_emoji_presentation = true` (or `false`) in [wezterm.font()](config/lua/wezterm/font.md) and [wezterm.font_with_fallback()](config/lua/wezterm/font_with_fallback.md)
 * Wayland: `zwp_text_input_v3` is now supported, which enables IME to work in wezterm if your compositor also implements this protocol.

docs/config/lua/wezterm.gui/get_appearance.md

@@ -0,0 +1,41 @@
+# `wezterm.gui.get_appearance()`
+
+*Since: nightly builds only*
+
+This function returns the appearance of the window environment.  The appearance
+can be one of the following 4 values:
+
+* `"Light"` - the normal appearance, with dark text on a light background
+* `"Dark"` - "dark mode", with predominantly dark colors and probably a lighter, lower contrasting, text color on a dark background
+* `"LightHighContrast"` - light mode but with high contrast colors (not reported on all systems)
+* `"DarkHighContrast"` - dark mode but with high contrast colors (not reported on all systems)
+
+wezterm is able to detect when the appearance has changed and will generate a
+[window-config-reloaded](../window-events/window-config-reloaded.md) event for
+each window.
+
+This example configuration shows how you can have your color scheme
+automatically adjust to the current appearance:
+
+```lua
+local wezterm = require 'wezterm'
+
+function scheme_for_appearance(appearance)
+  if appearance:find("Dark") then
+    return "Builtin Solarized Dark"
+  else
+    return "Builtin Solarized Light"
+  end
+end
+
+return {
+  color_scheme = scheme_for_appearance(wezterm.gui.get_appearance()),
+}
+```
+
+### Wayland GNOME Appearance
+
+wezterm uses [XDG Desktop
+Portal](https://flatpak.github.io/xdg-desktop-portal/) to determine the
+appearance in a desktop-environment independent way.
+

docs/config/lua/window/get_appearance.md

@@ -1,5 +1,7 @@
 # window:get_appearance()
 
+**NOTE: You probably want to use [wezterm.gui.get_appearance()](../wezterm.gui/get_appearance.md) instead, as it is easier to use!**
+
 *Since: 20210814-124438-54e29167*
 
 This method returns the appearance of the window environment.  The appearance

lua-api-crates/window-funcs/src/lib.rs

@@ -4,7 +4,7 @@ use luahelper::impl_lua_conversion_dynamic;
 use std::collections::HashMap;
 use std::rc::Rc;
 use wezterm_dynamic::{FromDynamic, ToDynamic};
-use window::{Connection, ConnectionOps};
+use window::{Appearance, Connection, ConnectionOps};
 
 fn get_conn() -> mlua::Result<Rc<Connection>> {
     Connection::get().ok_or_else(|| {
@@ -85,5 +85,18 @@ pub fn register(lua: &Lua) -> anyhow::Result<()> {
         })?,
     )?;
 
+    window_mod.set(
+        "get_appearance",
+        lua.create_function(|_, _: ()| {
+            Ok(match Connection::get() {
+                Some(conn) => conn.get_appearance().to_string(),
+                None => {
+                    // Gui hasn't started yet, assume light
+                    Appearance::Light.to_string()
+                }
+            })
+        })?,
+    )?;
+
     Ok(())
 }

wezterm-gui/src/frontend.rs

@@ -144,6 +144,10 @@ impl GuiFrontEnd {
                 false
             }
         });
+        // Re-evaluate the config so that folks that are using
+        // `wezterm.gui.get_appearance()` can have that take effect
+        // before any windows are created
+        config::reload();
         Ok(front_end)
     }