From ce2d37d5d96fe9ecb65c12c7eb5893814d3a5596 Mon Sep 17 00:00:00 2001
From: Emil Ernerfeldt <emil.ernerfeldt@gmail.com>
Date: Thu, 26 Jan 2023 16:05:52 +0100
Subject: [PATCH] Use "in front" and "behind" instead of "below" and "above"

---
 crates/egui/src/containers/panel.rs | 18 +++++-----
 crates/egui/src/layers.rs           | 54 +++++++++++++++++------------
 examples/z_order/src/main.rs        |  2 +-
 3 files changed, 42 insertions(+), 32 deletions(-)

diff --git a/crates/egui/src/containers/panel.rs b/crates/egui/src/containers/panel.rs
index a0644fcf..ca3cc1c5 100644
--- a/crates/egui/src/containers/panel.rs
+++ b/crates/egui/src/containers/panel.rs
@@ -308,10 +308,11 @@ impl SidePanel {
             };
             let resize_x = side.opposite().side_x(rect);
             let resize_x = ui.painter().round_to_pixel(resize_x);
-            ui.painter()
-                .clone()
-                .with_z(layers::ZOrder::ABOVE_ALL)
-                .vline(resize_x, rect.y_range(), stroke);
+            ui.painter().clone().with_z(layers::ZOrder::FRONT).vline(
+                resize_x,
+                rect.y_range(),
+                stroke,
+            );
         }
 
         inner_response
@@ -759,10 +760,11 @@ impl TopBottomPanel {
             };
             let resize_y = side.opposite().side_y(rect);
             let resize_y = ui.painter().round_to_pixel(resize_y);
-            ui.painter()
-                .clone()
-                .with_z(layers::ZOrder::ABOVE_ALL)
-                .hline(rect.x_range(), resize_y, stroke);
+            ui.painter().clone().with_z(layers::ZOrder::FRONT).hline(
+                rect.x_range(),
+                resize_y,
+                stroke,
+            );
         }
 
         inner_response
diff --git a/crates/egui/src/layers.rs b/crates/egui/src/layers.rs
index d3efd0f6..7b00fb3f 100644
--- a/crates/egui/src/layers.rs
+++ b/crates/egui/src/layers.rs
@@ -127,27 +127,32 @@ impl AreaLayerId {
 pub struct ZOrder(pub i32);
 
 impl ZOrder {
+    /// The default layer 0.
     pub const BASE: ZOrder = ZOrder(0);
-    pub const ABOVE_ALL: ZOrder = ZOrder(i32::MAX);
-    pub const BELOW_ALL: ZOrder = ZOrder(i32::MIN);
+
+    /// In front of everything else.
+    pub const FRONT: ZOrder = ZOrder(i32::MAX);
+
+    /// Behind everything else.
+    pub const BACK: ZOrder = ZOrder(i32::MIN);
 
     /// Directly above
-    pub fn above(self) -> Self {
-        self.above_by(1)
+    pub fn in_front(self) -> Self {
+        self.in_front_by(1)
     }
 
-    /// Directly below
-    pub fn below(self) -> Self {
-        self.below_by(1)
+    /// Directly behind
+    pub fn behind(self) -> Self {
+        self.behind_by(1)
     }
 
-    /// Above by the number of levels given
-    pub fn above_by(self, levels: i32) -> Self {
+    /// In front of by the number of levels given
+    pub fn in_front_by(self, levels: i32) -> Self {
         Self(self.0.saturating_add(levels))
     }
 
-    /// Below by the number of levels given
-    pub fn below_by(self, levels: i32) -> Self {
+    /// Behind by the number of levels given
+    pub fn behind_by(self, levels: i32) -> Self {
         Self(self.0.saturating_sub(levels))
     }
 }
@@ -175,6 +180,9 @@ impl std::ops::AddAssign<ZOffset> for ZOrder {
 // ----------------------------------------------------------------------------
 
 /// Offset within a [`ZOrder`].
+///
+/// * Positive: more in front of.
+/// * Negative: more behind.
 pub type ZOffset = i32;
 
 // ----------------------------------------------------------------------------
@@ -222,28 +230,28 @@ impl ZLayer {
         Self::from_area_layer_z(self.area_layer, z)
     }
 
-    /// Get the `ZLayer` directly above this one
+    /// Get the `ZLayer` directly in front of this one.
     #[must_use]
-    pub fn above(self) -> Self {
-        self.with_z(self.z.above())
+    pub fn in_front(self) -> Self {
+        self.with_z(self.z.in_front())
     }
 
-    /// Get the `ZLayer` above this one by `levels` levels
+    /// Get the `ZLayer` in front of this one by `levels` levels.
     #[must_use]
-    pub fn above_by(self, levels: i32) -> Self {
-        self.with_z(self.z.above_by(levels))
+    pub fn in_front_by(self, levels: i32) -> Self {
+        self.with_z(self.z.in_front_by(levels))
     }
 
-    /// Get the `ZLayer` directly below this one
+    /// Get the `ZLayer` directly behind this one.
     #[must_use]
-    pub fn below(self) -> Self {
-        self.with_z(self.z.below())
+    pub fn behind(self) -> Self {
+        self.with_z(self.z.behind())
     }
 
-    /// Get the `ZLayer` below this one by `levels` levels
+    /// Get the `ZLayer` behind this one by `levels` levels.
     #[must_use]
-    pub fn below_by(self, levels: i32) -> Self {
-        self.with_z(self.z.below_by(levels))
+    pub fn behind_by(self, levels: i32) -> Self {
+        self.with_z(self.z.behind_by(levels))
     }
 
     /// `Id` of underlying area layer
diff --git a/examples/z_order/src/main.rs b/examples/z_order/src/main.rs
index 1fa8d056..c104310d 100644
--- a/examples/z_order/src/main.rs
+++ b/examples/z_order/src/main.rs
@@ -72,7 +72,7 @@ impl eframe::App for MyApp {
                     }
 
                     let base = ZOrder::BASE;
-                    let above = base.above();
+                    let above = base.in_front();
 
                     draw_squares(ui, Vec2::new(0.0, 0.0), base, above);
                     draw_squares(ui, Vec2::new(100.0, 0.0), above, base);