Add new experimental feature flag

crates/eframe/Cargo.toml

@@ -52,6 +52,12 @@ android-native-activity = ["egui-winit/android-native-activity"]
 ## If you plan on specifying your own fonts you may disable this feature.
 default_fonts = ["egui/default_fonts"]
 
+## Enable experimental egui features that might have massive breaking changes or be removed entirely in future updates.
+## Enabling this won't break semver, it's just future compatibility risk.
+##
+## Currently, this enables the theme plugin.
+experimental = ["egui/experimental"]
+
 ## Enable [`glow`](https://github.com/grovesNL/glow) for painting, via [`egui_glow`](https://github.com/emilk/egui/tree/main/crates/egui_glow).
 ##
 ## There is generally no need to enable both the `wgpu` and `glow` features,

crates/egui/Cargo.toml

@@ -44,6 +44,12 @@ color-hex = ["epaint/color-hex"]
 ## If you plan on specifying your own fonts you may disable this feature.
 default_fonts = ["epaint/default_fonts"]
 
+## Enable experimental egui features that might have massive breaking changes or be removed entirely in future updates.
+## Enabling this won't break semver, it's just future compatibility risk.
+##
+## Currently, this enables the theme plugin.
+experimental = []
+
 ## [`mint`](https://docs.rs/mint) enables interoperability with other math libraries such as [`glam`](https://docs.rs/glam) and [`nalgebra`](https://docs.rs/nalgebra).
 mint = ["epaint/mint"]
 

crates/egui/src/context.rs

@@ -2030,6 +2030,7 @@ impl Context {
     }
 }
 
+/// Experimental theming, gated behind the `experimental_theme` feature.
 impl Context {
     /// Register a [`StyleProvider`](crate::theme::StyleProvider) for the specified widget type.
     ///
@@ -2037,6 +2038,7 @@ impl Context {
     /// If a theme is already registered for this widget, this is a no-op (useful for `eframe::run_simple_native`).
     ///
     /// If you want to add the theme anyway, use [`Self::replace_widget_theme`] instead.
+    #[cfg(feature = "experimental")]
     pub fn add_widget_theme<S: WidgetStyle + 'static>(
         &self,
         theme: impl theme::StyleProvider<S> + Send + Sync + 'static,
@@ -2048,6 +2050,7 @@ impl Context {
     ///
     /// Overwrite any theme already registered for the specified widget [`WidgetStyle`].
     /// This allow to live edit a theme.
+    #[cfg(feature = "experimental")]
     pub fn replace_widget_theme<S: WidgetStyle + 'static>(
         &self,
         theme: impl theme::StyleProvider<S> + Send + Sync + 'static,
@@ -2055,7 +2058,11 @@ impl Context {
         self.write(|ctx| ctx.themes.register::<S>(theme, true));
     }
 
-    /// Compute the [`WidgetStyle`] using the registered theme.
+    /// Compute the `WidgetStyle` using the registered theme.
+    ///
+    /// The types you need to call this (e.g. `StyleArgs`) are only public
+    /// with the `experimental_theme` feature.
+    #[cfg_attr(not(feature = "experimental"), doc(hidden))]
     pub fn get_widget_style<S: WidgetStyle + Clone + 'static>(
         &self,
         modifiers: &StyleArgs<'_>,

crates/egui/src/lib.rs

@@ -417,14 +417,20 @@ pub mod response;
 mod sense;
 pub mod style;
 pub mod text_selection;
+#[cfg(feature = "experimental")]
 pub mod theme;
+#[cfg(not(feature = "experimental"))]
+mod theme;
 mod ui;
 mod ui_builder;
 mod ui_stack;
 pub mod util;
 pub mod viewport;
 mod widget_rect;
+#[cfg(feature = "experimental")]
 pub mod widget_style;
+#[cfg(not(feature = "experimental"))]
+mod widget_style;
 pub mod widget_text;
 pub mod widgets;
 

crates/egui/src/theme/mod.rs

@@ -1,5 +1,9 @@
 //! Theming: pluggable [`StyleProvider`]s that compute the style of each widget.
 
+// This module is only public with the `experimental_theme` feature,
+// so without it a lot of it looks unused:
+#![cfg_attr(not(feature = "experimental"), allow(dead_code, unused_imports))]
+
 mod default_style;
 mod style_provider;
 mod themes;
@@ -12,8 +16,12 @@ use crate::{
 };
 
 impl Ui {
-    /// The style of the widget with the given [`crate::Id`] and [`Classes`],
+    /// The style of the widget with the given [`crate::Id`] and `Classes`,
     /// as computed by the registered theme.
+    ///
+    /// The types you need to call this are only public with the
+    /// `experimental_theme` feature.
+    #[cfg_attr(not(feature = "experimental"), doc(hidden))]
     pub fn widget_style<S: WidgetStyle + Clone + 'static>(
         &self,
         id: crate::Id,

crates/egui/src/widget_style/classes.rs

@@ -57,7 +57,7 @@ pub trait HasClasses {
 
     fn classes_mut(&mut self) -> &mut Classes;
 
-    /// Add the given class by consuming [`self`]
+    /// Add the given class by consuming `self`
     #[inline]
     fn with_class(mut self, class: impl Into<ClassName>) -> Self
     where
@@ -67,7 +67,7 @@ pub trait HasClasses {
         self
     }
 
-    /// Add the given class by consuming [`self`] if the condition is true
+    /// Add the given class by consuming `self` if the condition is true
     #[inline]
     fn with_class_if(mut self, class: impl Into<ClassName>, condition: bool) -> Self
     where

crates/egui/src/widget_style/mod.rs

@@ -1,3 +1,7 @@
+// This module is only public with the `experimental_theme` feature,
+// so without it a lot of it looks unused:
+#![cfg_attr(not(feature = "experimental"), allow(dead_code, unused_imports))]
+
 mod classes;
 
 pub use self::classes::{ClassName, Classes, HasClasses, ROOT_CLASS, SELECTED_CLASS};

examples/styling_engine/Cargo.toml

@@ -15,5 +15,6 @@ workspace = true
 eframe = { workspace = true, features = [
   "default",
   "__screenshot", # __screenshot is so we can dump a screenshot using EFRAME_SCREENSHOT_TO
+    "experimental", # this example is all about the experimental theming API
 ] }
 env_logger = { workspace = true, features = ["auto-color", "humantime"] }

tests/egui_tests/Cargo.toml

@@ -9,7 +9,7 @@ version.workspace = true
 ignored = ["image"] # We need the png feature
 
 [dev-dependencies]
-egui = { workspace = true, default-features = true }
+egui = { workspace = true, default-features = true, features = ["experimental"] }
 egui_kittest = { workspace = true, features = ["snapshot", "wgpu"] }
 egui_extras = { workspace = true, features = ["image"] }
 image = { workspace = true, features = ["png"] }