BufferView

A BufferView is a templated (generics based) control that displays and edits a byte buffer in a hex-editor style layout. It can show raw data in multiple representations (hexadecimal, octal, binary, integers, floats, or characters), optional address and interval-name columns, and optional character-decoding panels.

It can be created using BufferView::new(...), BufferView::with_buffer(...), or the bufferview! macro.

let bv1: BufferView<Vec<u8>> = BufferView::new(layout!("..."), bufferview::Flags::None);
let bv2: BufferView<Vec<u8>> = BufferView::with_buffer(vec![1, 2, 3], layout!("..."), bufferview::Flags::ScrollBars);
let bv3 = bufferview!("Vec<u8>, d:f, flags: ScrollBars+ShowAddress+SearchBar, columns: 8, format: Hex, offset: Hex");
let bv4 = bufferview!("Vec<u8>, d:f, flags: ShowAddress+ShowIntervalNames, format: Hex(Word), endian: Little");

where type T is the type of the backing store and must implement the BufferAccess trait. Vec<u8> is provided out of the box.

The bufferview! macro creates the control with a default-constructed backing buffer (T::default()). Load data at runtime with set_buffer or retrieve it with take_buffer.

A bufferview supports all common parameters (as they are described in Instantiate via Macros section). Besides them, the following named parameters are also accepted:

A bufferview supports the following initialization flags:

• bufferview::Flags::ScrollBars or ScrollBars (for macro initialization) - enables scroll bars for navigating through the buffer. The scroll bars are visible only when the control has focus.
• bufferview::Flags::SearchBar or SearchBar (for macro initialization) - enables a search bar for finding byte patterns. The search bar is visible only when the control has focus.
• bufferview::Flags::HideHeader or HideHeader (for macro initialization) - hides the column header row.
• bufferview::Flags::ShowAddress or ShowAddress (for macro initialization) - shows the address column on the left.
• bufferview::Flags::ShowIntervalNames or ShowIntervalNames (for macro initialization) - shows the interval-name column.
• bufferview::Flags::NoPanelDimming or NoPanelDimming (for macro initialization) - disables dimming of the inactive panel (data or character panel).
• bufferview::Flags::ShowAsciiStrings or ShowAsciiStrings (for macro initialization) - shows the ASCII string panel below the data area.
• bufferview::Flags::ShowUtf16AsciiStrings or ShowUtf16AsciiStrings (for macro initialization) - highlights UTF-16LE ASCII strings in the character panel.
• bufferview::Flags::DecodeUTF8Characters or DecodeUTF8Characters (for macro initialization) - decodes UTF-8 sequences in the character panel.
• bufferview::Flags::ReadOnly or ReadOnly (for macro initialization) - disables in-place editing.
• bufferview::Flags::TabSwitchesActivePanel or TabSwitchesActivePanel (for macro initialization) - makes the Tab key switch between the data panel and the character panel (instead of leaving the control).

Data representation formats

The main data panel can display buffer contents in several formats. The active format is set via the format macro parameter or with set_data_representation_format.

When a multi-byte format is active, the byte order is controlled by set_endian (Endian::Little or Endian::Big). The address column format is controlled separately via set_offset_format (OffsetFormat::Hex or OffsetFormat::Dec).

The number of columns per row can be fixed or computed automatically to fill the available width:

• ColumnsCount::Fixed(N) or macro columns: N / columns: Fixed(N) - exactly N columns per row.
• ColumnsCount::Auto or macro columns: Auto - as many columns as fit in the current control width.

BufferAccess

To connect a BufferView to your data, the backing type must implement the bufferview::BufferAccess trait:

pub trait BufferAccess : Default {
    fn count(&self) -> u64;
    fn get(&mut self, pos: u64) -> Option<u8>;
    fn can_write(&self) -> bool;
    fn set(&mut self, pos: u64, value: u8) -> bool;
    fn can_resize(&self) -> bool;
    fn resize(&mut self, new_size: u64, fill_byte: u8) -> bool;
}

• count returns the number of bytes in the buffer.
• get reads a byte at pos, or returns None if the position is not readable (for example a sparse or memory-mapped region).
• can_write / set control whether individual bytes can be modified in place.
• can_resize / resize control whether the buffer length can be changed.

Vec<u8> already implements BufferAccess. For custom sources (files, memory-mapped regions, read-only views, and so on), implement the trait on your own type. The examples/hexview sample shows a MyBuffer wrapper that exposes most bytes but marks a 100-byte region as unreadable.

Editing through the UI is allowed only when the backing buffer reports can_write() == true and the ReadOnly flag is not set.

Events

To intercept events from a bufferview, the following trait has to be implemented on the Window that processes the event loop. Use BufferViewEvents<T> in the #[Window(events = ...)] attribute, where T is the same BufferAccess type as the control:

pub trait BufferViewEvents<T: BufferAccess + 'static> {
    // called when the current byte position changes
    fn on_current_pos_changed(&mut self, handle: Handle<BufferView<T>>) -> EventProcessStatus {
        EventProcessStatus::Ignored
    }

    // called when the selected byte range changes
    fn on_selection_changed(&mut self, handle: Handle<BufferView<T>>) -> EventProcessStatus {
        EventProcessStatus::Ignored
    }
}

Methods

Besides the Common methods for all Controls a bufferview also has the following additional methods:

Buffer management

Display settings

Intervals

Cursor and selection

Buffer editing

These methods operate on the backing buffer when writes and resizing are allowed:

Key association

The following keys are processed by a BufferView control if it has focus:

While in column-resize mode (address or interval-name separator selected), the following keys are processed:

• Left, Right - decreases or increases the width of the selected column
• Tab, Ctrl+Left, Ctrl+Right, Ctrl+Alt+Left, Ctrl+Alt+Right - switches to the other resizable column separator
• Any other key - exits column-resize mode

Additionally, typing any character will open the search bar (if the SearchBar flag is present) and search for the next match. While the search bar is active:

• Backspace - removes the last character from the search text
• Escape - clears the search text and closes the search bar
• Enter - finds the next match
• Movement keys - close the search bar but keep the search text

Mouse interaction

• Left click on a byte moves the cursor to that position. Dragging extends the selection.
• Mouse wheel scrolls the view vertically; horizontal wheel scrolls horizontally when the data panel is wider than the visible area.
• Left click on a column header (Data or Char) activates that panel.
• Drag on a column separator resizes the address or interval-name column.

Search expressions

When the SearchBar flag is set, the search text is parsed into a byte pattern. If no prefix is given, the text is treated as plain bytes. Supported prefixes:

Each search updates the selection to the matched byte range and moves the cursor to the match.

Intervals

Intervals label byte ranges in the interval-name column. Overlapping intervals are supported; the innermost interval name is shown for each byte.

An interval is created with bufferview::Interval::new(start, size, attr, name):

• start - the first byte offset of the interval
• size - the number of bytes covered
• attr - the CharAttribute used to render the name
• name - the text shown in the interval-name column

bv.set_intervals(&[
    bufferview::Interval::new(0, 16, CharAttribute::with_fore_color(Color::Red), "Header"),
    bufferview::Interval::new(16, 32, CharAttribute::with_fore_color(Color::Green), "Payload"),
]);

Example

The following example creates a window with a hex view over a Vec<u8> buffer. Moving the cursor updates the window title. Two labeled intervals highlight the greeting and the payload regions.

use appcui::prelude::*;

#[Window(events = BufferViewEvents<Vec<u8>>)]
struct HexWindow {
    buffer_view: Handle<BufferView<Vec<u8>>>,
}

impl HexWindow {
    fn new() -> Self {
        let mut w = Self {
            base: window!("Hex View,d:f,flags:Sizeable"),
            buffer_view: Handle::None,
        };
        let mut bv = bufferview!(
            "Vec<u8>, 
            d:f, 
            flags: ScrollBars+ShowAddress+ShowIntervalNames+SearchBar,
            columns: 8, 
            format: Hex, 
            offset: Hex"
        );
        bv.set_buffer(b"Hello, AppCUI!".to_vec());
        bv.set_intervals(&[
            bufferview::Interval::new(0, 7, CharAttribute::with_fore_color(Color::Cyan), "Greeting"),
            bufferview::Interval::new(7, 6, CharAttribute::with_fore_color(Color::Yellow), "Payload"),
        ]);
        w.buffer_view = w.add(bv);
        w.update_title();
        w
    }

    fn update_title(&mut self) {
        let h = self.buffer_view;
        if let Some(bv) = self.control(h) {
            self.set_title(&format!("Hex View - position {}", bv.current_pos()));
        }
    }
}

impl BufferViewEvents<Vec<u8>> for HexWindow {
    fn on_current_pos_changed(&mut self, handle: Handle<BufferView<Vec<u8>>>) -> EventProcessStatus {
        if handle == self.buffer_view {
            self.update_title();
        }
        EventProcessStatus::Processed
    }
}

fn main() -> Result<(), appcui::system::Error> {
    let mut app = App::new().build()?;
    app.add_window(HexWindow::new());
    app.run();
    Ok(())
}

For a full-featured hex editor with format switching, code-page selection, and buffer editing commands, see the examples/hexview sample in the repository.