Support using heh as a Ratatui widget

README.md

@@ -84,6 +84,45 @@ pacman -S heh
 apk add heh
 ```
 
+## Using as a Ratatui widget
+
+`heh` can be used a library and embedded into other TUI applications which use [Ratatui](https://ratatui.rs) and [crossterm](https://github.com/crossterm-rs/crossterm).
+
+Add `heh` to your dependencies in `Cargo.toml`:
+
+```toml
+[dependencies]
+ratatui = "0.24"
+crossterm = "0.27"
+heh = "0.4"
+```
+
+Create the application:
+
+```rust
+use heh::app::Application as Heh;
+use heh::decoder::Encoding;
+
+let file = std::fs::OpenOptions::new().read(true).write(true).open(path).unwrap();
+let heh = Heh::new(file, Encoding::Ascii, 0).unwrap();
+```
+
+Then you can render a frame as follows:
+
+```rust
+terminal.draw(|frame| {
+    heh.render_frame(frame, frame.size());
+});
+```
+
+To handle key events:
+
+```rust
+heh.handle_input(&crossterm::event::Event::Key(/* */)).unwrap();
+```
+
+See the [binsider](https://github.com/orhun/binsider) project for an example use case.
+
 # Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).

src/app.rs

@@ -2,19 +2,24 @@
 //!
 //! The application holds the main components of the other modules, like the [`ScreenHandler`],
 //! [`LabelHandler`], and input handling, as well as the state data that each of them need.
+//!
+//! [`ScreenHandler`]: crate::screen::Handler
+//! [`LabelHandler`]: crate::label::Handler
 
 use std::{error::Error, fs::File, process};
 
 use arboard::Clipboard;
 use crossterm::event::{self, Event, KeyEventKind};
+use ratatui::layout::Rect;
+use ratatui::Frame;
 
 use crate::buffer::AsyncBuffer;
 use crate::decoder::Encoding;
 use crate::windows::search::Search;
 use crate::{
     input,
-    label::LabelHandler,
-    screen::ScreenHandler,
+    label::Handler as LabelHandler,
+    screen::Handler as ScreenHandler,
     windows::{
         editor::Editor, jump_to_byte::JumpToByte, unsaved_changes::UnsavedChanges, KeyHandler,
         Window,
@@ -53,9 +58,9 @@
 }
 
 /// State Information needed by the [`ScreenHandler`] and [`KeyHandler`].
-pub(crate) struct AppData {
+pub struct Data {
     /// The file under editing.
-    pub(crate) file: File,
+    pub file: File,
 
     /// The file content.
     pub(crate) contents: AsyncBuffer,
@@ -103,7 +108,7 @@
     pub(crate) search_offsets: Vec<usize>,
 }
 
-impl AppData {
+impl Data {
     /// Reindexes contents to find locations of the user's search term.
     pub(crate) fn reindex_search(&mut self) {
         self.search_offsets = self
@@ -117,32 +122,30 @@
 
 /// Application provides the user interaction interface and renders the terminal screen in response
 /// to user actions.
-pub(crate) struct Application {
+pub struct Application {
     /// The application's state and data.
-    pub(crate) data: AppData,
+    pub data: Data,
 
     /// Renders and displays objects to the terminal.
     pub(crate) display: ScreenHandler,
 
     /// The labels at the bottom of the UI that provide information
     /// based on the current offset.
-    pub(crate) labels: LabelHandler,
+    pub labels: LabelHandler,
 
     /// The window that handles keyboard input. This is usually in the form of the Hex/ASCII editor
     /// or popups.
-    pub(crate) key_handler: Box<dyn KeyHandler>,
+    pub key_handler: Box<dyn KeyHandler>,
 }
 
 impl Application {
     /// Creates a new application, focusing the Hex editor and starting with an offset of 0 by
     /// default. This is called once at the beginning of the program.
     ///
+    /// # Errors
+    ///
     /// This errors out if the file specified is empty.
-    pub(crate) fn new(
-        file: File,
-        encoding: Encoding,
-        offset: usize,
-    ) -> Result<Self, Box<dyn Error>> {
+    pub fn new(file: File, encoding: Encoding, offset: usize) -> Result<Self, Box<dyn Error>> {
         let contents = AsyncBuffer::new(&file)?;
         if contents.is_empty() {
             eprintln!("heh does not support editing empty files");
@@ -164,7 +167,7 @@
         let display = ScreenHandler::new()?;
 
         let app = Self {
-            data: AppData {
+            data: Data {
                 file,
                 contents,
                 encoding,
@@ -193,11 +196,16 @@
 
     /// A loop that repeatedly renders the terminal and modifies state based on input. Is stopped
     /// when input handling receives CNTRLq, the command to stop.
-    pub(crate) fn run(&mut self) -> Result<(), Box<dyn Error>> {
+    ///
+    /// # Errors
+    ///
+    /// This errors when the UI fails to render.
+    pub fn run(&mut self) -> Result<(), Box<dyn Error>> {
         ScreenHandler::setup()?;
         loop {
             self.render_display()?;
-            if !self.handle_input()? {
+            let event = event::read()?;
+            if !self.handle_input(&event)? {
                 break;
             }
         }
@@ -208,25 +216,54 @@
     /// Renders the display. This is a wrapper around [`ScreenHandler`'s
     /// render](ScreenHandler::render) method.
     fn render_display(&mut self) -> Result<(), Box<dyn Error>> {
-        self.display.render(&mut self.data, &self.labels, self.key_handler.as_ref())?;
-        Ok(())
+        self.display.render(&mut self.data, &self.labels, self.key_handler.as_ref())
+    }
+
+    /// Renders a single frame for the given area.
+    pub fn render_frame(&mut self, frame: &mut Frame, area: Rect) {
+        self.data.contents.compute_new_window(self.data.offset);
+        // We check if we need to recompute the terminal size in the case that the saved off
+        // variable differs from the current frame, which can occur when a terminal is resized
+        // between an event handling and a rendering.
+        if area != self.display.terminal_size {
+            self.display.terminal_size = area;
+            self.display.comp_layouts =
+                ScreenHandler::calculate_dimensions(area, self.key_handler.as_ref());
+            // We change the start_address here to ensure that 0 is ALWAYS the first start
+            // address. We round to preventing constant resizing always moving to 0.
+            self.data.start_address = (self.data.start_address
+                + (self.display.comp_layouts.bytes_per_line / 2))
+                / self.display.comp_layouts.bytes_per_line
+                * self.display.comp_layouts.bytes_per_line;
+        }
+        ScreenHandler::render_frame(
+            frame,
+            self.display.terminal_size,
+            &mut self.data,
+            &self.labels,
+            self.key_handler.as_ref(),
+            &self.display.comp_layouts,
+        );
     }
 
     /// Handles all forms of user input. This calls out to code in [input], which uses
     /// [Application's `key_handler` method](Application::key_handler) to determine what to do for
     /// key input.
-    fn handle_input(&mut self) -> Result<bool, Box<dyn Error>> {
-        let event = event::read()?;
+    ///
+    /// # Errors
+    ///
+    /// This errors when handling the key event fails.
+    pub fn handle_input(&mut self, event: &Event) -> Result<bool, Box<dyn Error>> {
         match event {
             Event::Key(key) => {
                 if key.kind == KeyEventKind::Press {
                     self.labels.notification.clear();
-                    return input::handle_key_input(self, key);
+                    return input::handle_key_input(self, *key);
                 }
             }
             Event::Mouse(mouse) => {
                 self.labels.notification.clear();
-                input::handle_mouse_input(self, mouse);
+                input::handle_mouse_input(self, *mouse);
             }
             Event::Resize(_, _) | Event::FocusGained | Event::FocusLost | Event::Paste(_) => {}
         }

src/decoder.rs

@@ -1,3 +1,5 @@
+//! Decoder utilities.
+
 use std::str::from_utf8;
 
 use crate::character::{Category, RichChar, Type, CHARACTER_FILL, CHARACTER_UNKNOWN};
@@ -80,7 +82,7 @@ impl<'a> Iterator for LossyUTF8Decoder<'a> {
 }
 
 #[derive(Copy, Clone, Debug)]
-pub(crate) enum Encoding {
+pub enum Encoding {
     Ascii,
     Utf8,
 }

src/label.rs

@@ -42,7 +42,7 @@ impl fmt::Display for Endianness {
 }
 
 #[derive(Default)]
-pub(crate) struct LabelHandler {
+pub struct Handler {
     signed_eight: String,
     signed_sixteen: String,
     signed_thirtytwo: String,
@@ -59,11 +59,11 @@ pub(crate) struct LabelHandler {
     stream_length: usize,
     stream_length_string: String,
     pub(crate) offset: String,
-    pub(crate) notification: String,
+    pub notification: String,
     pub(crate) endianness: Endianness,
 }
 
-impl Index<&str> for LabelHandler {
+impl Index<&str> for Handler {
     type Output = String;
 
     fn index(&self, index: &str) -> &Self::Output {
@@ -89,7 +89,7 @@ impl Index<&str> for LabelHandler {
     }
 }
 
-impl LabelHandler {
+impl Handler {
     pub(crate) fn new(bytes: &[u8], offset: usize) -> Self {
         let mut labels = Self { ..Default::default() };
         labels.update_stream_length(8);
@@ -243,7 +243,7 @@ mod tests {
     fn test_binary_label() {
         // Given a label handler with the content 'hello' and offset of 0
         let content = "hello".as_bytes();
-        let mut label_handler = LabelHandler::new(content, 0);
+        let mut label_handler = Handler::new(content, 0);
         // The binary label should contain the binary veresion of the first character
         assert!(label_handler.binary.eq("01101000"));
 

src/lib.rs

@@ -0,0 +1,9 @@
+pub mod app;
+mod buffer;
+mod character;
+mod chunk;
+pub mod decoder;
+pub mod input;
+pub mod label;
+pub mod screen;
+pub mod windows;

src/main.rs

@@ -10,19 +10,8 @@ use std::{error::Error, fs::OpenOptions, io, process};
 use clap::{Parser, ValueEnum};
 use crossterm::tty::IsTty;
 
-use app::Application;
-
-use crate::decoder::Encoding;
-
-mod app;
-mod buffer;
-mod character;
-mod chunk;
-mod decoder;
-mod input;
-mod label;
-mod screen;
-mod windows;
+use heh::app::Application;
+use heh::decoder::Encoding;
 
 const ABOUT: &str = "
 A HEx Helper to edit bytes by the nibble.