document render_scope.rs #13

src/render_scope.rs

@@ -1,3 +1,13 @@
+//! Rendering logic and layout scope management for OSUI.
+//!
+//! `RenderScope` is responsible for handling transformations, parent-child dimensions,
+//! stacking draw operations, and rendering styled output to the terminal.
+//!
+//! This module allows widgets to accumulate rendering commands (text, shapes, colors),
+//! and then flush them to the screen with correct styling and positioning.
+//!
+//! Used internally by OSUI's layout and rendering system.
+
 use std::fmt::Debug;
 
 use crate::{
@@ -5,13 +15,21 @@ use crate::{
     utils::{self, hex_ansi_bg},
 };
 
+/// Represents a single render instruction.
 #[derive(Clone)]
 enum RenderMethod {
+    /// Plain text rendering at current transform.
     Text(String),
+    /// Text rendered with a specific 24-bit color.
     TextColored(String, u32),
+    /// A filled rectangle of a given size and background color.
     Rectangle(u16, u16, u32),
 }
 
+/// Stores renderable state and transformation data for a single UI widget.
+///
+/// `RenderScope` tracks dimensions, styles, and draw commands such as text or
+/// background rectangles. It accumulates instructions that are later executed in the `draw` method.
 #[derive(Clone)]
 pub struct RenderScope {
     transform: RawTransform,
@@ -22,6 +40,7 @@ pub struct RenderScope {
 }
 
 impl RenderScope {
+    /// Creates a new, empty `RenderScope`.
     pub fn new() -> RenderScope {
         RenderScope {
             transform: RawTransform::new(),
@@ -32,10 +51,12 @@ impl RenderScope {
         }
     }
 
+    /// Directly sets the raw transform (position and size) for this scope.
     pub fn set_transform_raw(&mut self, transform: RawTransform) {
         self.transform = transform;
     }
 
+    /// Applies a `Transform` to this scope, factoring in parent dimensions.
     pub fn set_transform(&mut self, transform: &Transform) {
         transform.use_dimensions(self.parent_width, self.parent_height, &mut self.transform);
         transform.use_position(self.parent_width, self.parent_height, &mut self.transform);
@@ -43,6 +64,7 @@ impl RenderScope {
         self.transform.py = transform.py;
     }
 
+    /// Adds a text draw instruction.
     pub fn draw_text(&mut self, text: &str) {
         self.render_stack.push(RenderMethod::Text(text.to_string()));
         let (w, h) = utils::str_size(text);
@@ -50,6 +72,7 @@ impl RenderScope {
         self.transform.height = self.transform.height.max(h);
     }
 
+    /// Adds a colored text draw instruction.
     pub fn draw_text_colored(&mut self, text: &str, color: u32) {
         self.render_stack
             .push(RenderMethod::TextColored(text.to_string(), color));
@@ -58,6 +81,7 @@ impl RenderScope {
         self.transform.height = self.transform.height.max(h);
     }
 
+    /// Adds a background rectangle draw instruction.
     pub fn draw_rect(&mut self, width: u16, height: u16, color: u32) {
         self.render_stack
             .push(RenderMethod::Rectangle(width, height, color));
@@ -65,17 +89,25 @@ impl RenderScope {
         self.transform.height = self.transform.height.max(height);
     }
 
+    /// Manually ensures a minimum area is allocated.
     pub fn use_area(&mut self, width: u16, height: u16) {
         self.transform.width = self.transform.width.max(width);
         self.transform.height = self.transform.height.max(height);
     }
 
+    /// Renders the current stack to the terminal.
+    ///
+    /// This will draw background styles (e.g. solid fill or outline) first,
+    /// followed by each draw instruction in the stack.
     pub fn draw(&self) {
         let width = self.transform.width;
         let height = self.transform.height;
+
         match self.style.background {
             crate::style::Background::NoBackground => {}
-            crate::style::Background::Outline(_c) => {}
+            crate::style::Background::Outline(_c) => {
+                // TODO: Implement basic outline drawing if needed
+            }
             crate::style::Background::RoundedOutline(c) => {
                 let width = width + self.transform.px * 2;
                 let height = height + self.transform.py * 2;
@@ -134,16 +166,19 @@ impl RenderScope {
         }
     }
 
+    /// Clears all render instructions and resets the internal state.
     pub fn clear(&mut self) {
         self.render_stack.clear();
         self.transform = RawTransform::new();
         self.style = Style::new();
     }
 
+    /// Gets the currently used width and height.
     pub fn get_size(&self) -> (u16, u16) {
         (self.transform.width, self.transform.height)
     }
 
+    /// Returns current size, or defaults if size is zero.
     pub fn get_size_or(&self, width: u16, height: u16) -> (u16, u16) {
         (
             if self.transform.width == 0 {
@@ -159,6 +194,7 @@ impl RenderScope {
         )
     }
 
+    /// Returns size, falling back to parent size if unset.
     pub fn get_size_or_parent(&self) -> (u16, u16) {
         (
             if self.transform.width == 0 {
@@ -174,27 +210,33 @@ impl RenderScope {
         )
     }
 
+    /// Gets the dimensions of the parent container.
     pub fn get_parent_size(&self) -> (u16, u16) {
         (self.parent_width, self.parent_height)
     }
 
+    /// Sets the dimensions of the parent container.
     pub fn set_parent_size(&mut self, width: u16, height: u16) {
         self.parent_width = width;
         self.parent_height = height;
     }
 
+    /// Returns a mutable reference to the internal raw transform.
     pub fn get_transform_mut(&mut self) -> &mut RawTransform {
         &mut self.transform
     }
 
+    /// Returns a reference to the internal raw transform.
     pub fn get_transform(&self) -> &RawTransform {
         &self.transform
     }
 
+    /// Sets the style for the current render scope.
     pub fn set_style(&mut self, style: Style) {
         self.style = style;
     }
 
+    /// Gets a mutable reference to the style.
     pub fn get_style(&mut self) -> &mut Style {
         &mut self.style
     }