Support using heh as a Ratatui widget

README.md

@@ -84,6 +84,43 @@ 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();
+```
+
 # Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).

src/app.rs

@@ -7,6 +7,8 @@
 
 use arboard::Clipboard;
 use crossterm::event::{self, Event, KeyEventKind};
+use ratatui::layout::Rect;
+use ratatui::Frame;
 
 use crate::buffer::AsyncBuffer;
 use crate::decoder::Encoding;
@@ -53,9 +55,9 @@
 }
 
 /// State Information needed by the [`ScreenHandler`] and [`KeyHandler`].
-pub(crate) struct AppData {
+pub struct AppData {
     /// The file under editing.
-    pub(crate) file: File,
+    pub file: File,
 
     /// The file content.
     pub(crate) contents: AsyncBuffer,
@@ -117,16 +119,16 @@
 
 /// 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: AppData,
 
     /// 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.
@@ -138,11 +140,7 @@
     /// default. This is called once at the beginning of the program.
     ///
     /// 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");
@@ -193,11 +191,12 @@
 
     /// 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>> {
+    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,15 +207,40 @@
     /// 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()?;
+    pub fn handle_input(&mut self, event: Event) -> Result<bool, Box<dyn Error>> {
         match event {
             Event::Key(key) => {
                 if key.kind == KeyEventKind::Press {

src/decoder.rs

@@ -80,7 +80,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 LabelHandler {
     signed_eight: String,
     signed_sixteen: String,
     signed_thirtytwo: String,
@@ -59,7 +59,7 @@ 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,
 }
 

src/lib.rs

@@ -0,0 +1,9 @@
+pub mod app;
+mod buffer;
+mod character;
+mod chunk;
+pub mod decoder;
+mod input;
+mod label;
+pub mod screen;
+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.