From 3bc00f5f3f030acc8dbbf8018f6c2a99561ca709 Mon Sep 17 00:00:00 2001
From: tomsmeding <tom.smeding@gmail.com>
Date: Sun, 10 Feb 2019 20:37:02 +0100
Subject: Update organisation and document

---
 src/widgets/log.rs    | 39 +++++++++++++++++++++++++--------------
 src/widgets/menu.rs   | 11 +++++++++++
 src/widgets/prompt.rs | 35 ++++++++++++++++++++++++-----------
 3 files changed, 60 insertions(+), 25 deletions(-)

(limited to 'src/widgets')

diff --git a/src/widgets/log.rs b/src/widgets/log.rs
index 8bd240a..4966cc0 100644
--- a/src/widgets/log.rs
+++ b/src/widgets/log.rs
@@ -1,27 +1,44 @@
+//! Logging events in a scrolling list.
+//!
+//! Events are logged in an upwards scrolled box that forgets about the events
+//! that move off-screen. The logger may optionally add timestamps to events.
+//!
+//! To create a log widget, make a `LogBuilder`, optionally modify properties,
+//! and then use its `create` method to create a `Log` object.
+
 use std::ptr;
 
 use crate::bindings;
+use crate::core::Screen;
 
 pub struct Log {
     ptr: *mut bindings::Logwidget,
 }
 
-pub struct LogBuilder<'a> {
+pub struct LogBuilder<'a, 'b> {
+    _screen: &'a Screen<'b>,
     lefttop: (u32, u32),
     size: (u32, u32),
     title: Option<&'a str>,
     timestamps: bool,
 }
 
-impl<'a> LogBuilder<'a> {
-    pub fn add_title<'s: 'a>(&'a mut self, title: &'s str)
-                -> &'a mut LogBuilder<'a> {
+impl<'a, 'b> LogBuilder<'a, 'b> {
+    pub fn new(screen: &'a Screen<'b>, lefttop: (u32, u32), size: (u32, u32)) -> Self {
+        LogBuilder {
+            _screen: screen,
+            lefttop, size,
+            title: None,
+            timestamps: false,
+        }
+    }
+
+    pub fn add_title<'s: 'a>(&mut self, title: &'s str) -> &mut Self {
         self.title = Some(title);
         self
     }
 
-    pub fn set_timestamps(&'a mut self, timestamps: bool)
-                -> &'a mut LogBuilder<'a> {
+    pub fn set_timestamps(&mut self, timestamps: bool) -> &mut Self {
         self.timestamps = timestamps;
         self
     }
@@ -43,14 +60,8 @@ impl<'a> LogBuilder<'a> {
 }
 
 impl Log {
-    pub fn new<'a>(lefttop: (u32, u32), size: (u32, u32)) -> LogBuilder<'a> {
-        LogBuilder {
-            lefttop, size,
-            title: None,
-            timestamps: false,
-        }
-    }
-
+    /// Called automatically; should only be needed if something else overwrote
+    /// the widget.
     pub fn redraw(&self) {
         unsafe { bindings::lgw_redraw(self.ptr); }
     }
diff --git a/src/widgets/menu.rs b/src/widgets/menu.rs
index fe899e3..f90e62b 100644
--- a/src/widgets/menu.rs
+++ b/src/widgets/menu.rs
@@ -1,3 +1,9 @@
+//! A selection menu.
+//!
+//! The configuration for a menu is encapsulated in a `Data` struct, which
+//! contains some number of `Item` structs which describe the individual items
+//! to be chosen between.
+
 use std::ffi::c_void;
 
 use crate::bindings;
@@ -46,10 +52,15 @@ impl Menu {
         }
     }
 
+    /// Called automatically; should only be needed if something else overwrote
+    /// the widget.
     pub fn redraw(&self) {
         unsafe { bindings::menu_redraw(self.ptr); }
     }
 
+    /// Process the given key in the context of the menu.
+    ///
+    /// The key should be a return value from `Keyboard::get_key()`.
     pub fn handle_key(&mut self, key: i32) -> KeyResult {
         match unsafe { bindings::menu_handlekey(self.ptr, key) } {
             bindings::Menukey_MENUKEY_HANDLED => KeyResult::Handled,
diff --git a/src/widgets/prompt.rs b/src/widgets/prompt.rs
index 0690840..31c8630 100644
--- a/src/widgets/prompt.rs
+++ b/src/widgets/prompt.rs
@@ -1,21 +1,36 @@
+//! A box for getting a line of text input.
+//!
+//! To create a prompt widget, make a `PromptBuilder`, optionally modify
+//! properties, and then use its `create` method to create a `Prompt` object.
+
 use std::ptr;
 
 use crate::bindings;
+use crate::core::Screen;
 use crate::util;
 
 pub struct Prompt {
     ptr: *mut bindings::Promptwidget,
 }
 
-pub struct PromptBuilder<'a> {
+pub struct PromptBuilder<'a, 'b> {
+    _screen: &'a Screen<'b>,
     lefttop: (u32, u32),
     width: u32,
     title: Option<&'a str>,
 }
 
-impl<'a> PromptBuilder<'a> {
-    pub fn add_title<'s: 'a>(&'a mut self, title: &'s str)
-                -> &'a mut PromptBuilder<'a> {
+impl<'a, 'b> PromptBuilder<'a, 'b> {
+    pub fn new(screen: &'a Screen<'b>, lefttop: (u32, u32), width: u32) -> Self {
+        PromptBuilder {
+            _screen: screen,
+            lefttop, width,
+            title: None,
+        }
+    }
+
+    pub fn add_title<'s: 'a>(&mut self, title: &'s str)
+                -> &mut Self {
         self.title = Some(title);
         self
     }
@@ -36,17 +51,15 @@ impl<'a> PromptBuilder<'a> {
 }
 
 impl Prompt {
-    pub fn new<'a>(lefttop: (u32, u32), width: u32) -> PromptBuilder<'a> {
-        PromptBuilder {
-            lefttop, width,
-            title: None,
-        }
-    }
-
+    /// Called automatically; should only be needed if something else overwrote
+    /// the widget.
     pub fn redraw(&self) {
         unsafe { bindings::prw_redraw(self.ptr); }
     }
 
+    /// Input string if <enter>, None otherwise.
+    ///
+    /// The key should be a return value from `Keyboard::get_key()`.
     pub fn handle_key(&mut self, key: i32) -> Option<String> {
         let ptr = unsafe { bindings::prw_handlekey(self.ptr, key) };
         if ptr.is_null() {
-- 
cgit v1.2.3-70-g09d2