Building a Human68k file manager with a text mode UI

A file manager is an excellent way to learn how the Sharp X68000 turns a simple command-line environment into an interactive desktop tool. The project combines directory traversal, keyboard handling, screen layout, sorting, file operations and careful use of limited memory. It also gives a practical reason to understand Human68k rather than treating the machine as a black box.

The finished program does not need sprites, a mouse or a graphical shell. A responsive text mode interface can show two directory panels, a status line, keyboard shortcuts and a small operation prompt while leaving enough resources for real file work. On original hardware, that restraint is part of the appeal: every redraw, buffer and system call has a visible cost.

Defining the Human68k environment

Human68k is closely related to DOS in its command-oriented design, but it has its own conventions, device drivers and system interfaces. A file manager should therefore be designed around the facilities available on the target machine rather than assuming that a modern C runtime, Unicode support or POSIX directory API exists.

A sensible first target is a single-tasking utility written in C with small assembly helpers only where timing or direct hardware access demands them. The program can obtain directory entries through the Human68k DOS interface or compiler-provided wrappers, store a compact list in memory, and draw the visible rows through the console device. Keeping operating-system calls behind a small abstraction layer makes it easier to test code on an emulator and later adapt it to a different compiler.

The first prototype should list one directory, show file names and sizes, and respond to cursor keys. Avoid adding copying and deletion until the display and input loop behave reliably. A predictable sequence—read input, update state, redraw only what changed—will prevent many bugs that become difficult to isolate once file operations and prompts are mixed together.

Designing a useful text interface

An 80-column layout is a practical starting point for a Human68k file manager. Two panels of roughly 38 columns can show names, attributes and compact size information, with a narrow divider between them. The bottom two lines can contain the current path, free space, selected item and available commands. If the selected name is longer than the panel, scrolling it horizontally is usually less confusing than truncating it without explanation.

Keyboard navigation should remain discoverable. Cursor keys move the selection, Return opens a directory or launches a file, Backspace moves to the parent directory, Tab changes panels, and a small set of function keys handles copying, moving, deleting and renaming. Displaying these bindings in a status line is especially helpful when using several Japanese keyboard layouts or an emulator with remapped keys.

Use a state machine rather than a collection of deeply nested input loops. States such as browsing, entering a path, confirming deletion and choosing a copy destination give each action a clear escape route. A modal confirmation should accept a narrow set of inputs, such as Y, N and Escape, and must never interpret an old keypress left in the input buffer as approval for a destructive operation.

Reading directories and representing files

Directory enumeration is where a portable-looking program often becomes platform-specific. Human68k file names may use Shift-JIS, and the display width of Japanese characters is not always equivalent to the number of bytes in the name. A byte-based truncation routine can split a multibyte character and leave unreadable output, so the user interface should walk character boundaries before applying a column limit.

A useful internal record contains the original name, a display name or cached width, file size, date, time, attribute bits and an entry type. Keep the original path separate from the rendered label. That separation prevents padding, colour-control sequences or abbreviated text from accidentally being passed back to the file API.

Sorting should be explicit and stable. Name order is the default, but size, extension and modification time are useful alternatives. Directories normally appear first, with “.” and “..” handled as navigation concepts rather than ordinary entries. If memory is tight, sort an array of compact records or pointers instead of copying full path strings into every item.

The file manager can feel considerably faster if it avoids rebuilding both panels after every cursor movement. Read a directory only when its path or sort mode changes, then redraw the selected row and status area. For a large disk image, this distinction matters even when the actual hardware is an emulated X68000 running on a modern Australian desktop.

Design area	Practical choice	Reason on original hardware
Screen layout	Two panels with a fixed status bar	Keeps navigation visible without requiring a graphics mode
Input	Raw key handling with a state machine	Separates browsing from confirmation and path entry
Directory data	Compact records plus a string pool	Reduces repeated path and name storage
Character handling	Shift-JIS-aware truncation	Avoids broken Japanese file names
Sorting	Name first, optional size/date modes	Gives predictable results and manageable code
Redrawing	Update changed rows and panels only	Reduces flicker and console traffic
File copying	Buffered blocks with progress	Works within memory limits and shows activity
Error reporting	Preserve DOS error codes and plain wording	Makes failed operations diagnosable on real machines

Drawing and handling keyboard input

There are two broad approaches to the display. The conservative method writes text and escape sequences through the console device, allowing the Human68k environment to manage cursor positioning and attributes. The faster method writes directly to text VRAM or uses low-level IOCS services. Console output is easier to port and debug; direct access can produce a cleaner experience once the layout is stable.

A redraw routine should know the panel rectangles, active row, inactive row and status regions. Painting a row should first clear its full width, then draw the entry name and aligned metadata. This avoids remnants from a long filename remaining after a shorter one replaces it. Colour or inverse video can identify the active panel, but the program should retain a monochrome-friendly mode for composite displays and capture cards.

Keyboard input needs more care than reading ordinary characters from standard input. Cursor and function keys generally arrive as escape sequences or platform-specific scan codes, while repeated keys may generate events faster than a directory operation can complete. Convert raw input into a small set of internal commands such as KEY_UP, KEY_ENTER and KEY_COPY. That keeps the browsing logic independent of the physical keyboard encoding.

A timer is useful for cursor blinking, but it is not essential for the first version. The application should never wait indefinitely for a redraw timer while a key is pending. Non-blocking input, or a short polling loop with a controlled delay, gives a more responsive result. On real hardware, test with a slow floppy drive and a hard-disk image rather than relying exclusively on an emulator.

Adding copy, move and delete operations

File operations should be treated as transactions with visible progress and clear failure handling. Copying requires opening the source, creating the destination, reading a moderate buffer, writing the bytes, checking each result and preserving the original timestamp where the platform permits it. A progress indicator based on bytes transferred is useful, but the display must also handle unknown or changing file sizes.

Moving within one volume may be implemented as a rename, while moving between volumes requires copy followed by a successful delete. That distinction should be reflected in the status message. If a copy fails halfway through, the destination should be closed and either removed or marked as incomplete, rather than presented as a normal finished file.

Deletion deserves a stronger confirmation than renaming. Show the complete path, distinguish files from directories, and require a second confirmation for recursive directory removal. Human68k attributes may make a file read-only or otherwise protected, so the program should report the actual DOS error instead of silently retrying with altered attributes.

For transfers involving modern machines, a compact progress display is more valuable than decorative effects. Enthusiasts often move disk images through emulators, CompactFlash adapters or networked storage, then inspect them on original hardware. The same interface should therefore cope with removable media being absent, write-protected or slower than expected.

Extending the interface beyond plain listings

The text UI can grow without becoming a graphical shell. A quick-view pane could display the first part of a text file, while a hex view would help inspect disk images, save files and suspicious archive headers. These views should be read-only and bounded, so opening a large file cannot consume all available memory.

A command line at the bottom is another useful extension. It can accept a path, wildcard or Human68k command, then return to the same panel state after execution. Shell integration must preserve the current directory and restore the screen cleanly, otherwise a failed command can leave the interface looking frozen. Capturing standard output into a scrollback buffer is preferable to assuming the command will fit on one screen.

The project can also borrow ideas from the machine’s broader hobbyist culture. A compact text manager is a good companion for utilities that prepare assets, inspect disks or organise files used by games and demos. When a project later needs animated previews or a graphical browser, the sprite engine notes provide useful context for moving beyond character-cell output without abandoning the constraints of the platform.

Australian owners may encounter a few practical differences from Japanese documentation. A machine running in Sydney, Melbourne or Perth is connected to a 230 V, 50 Hz supply, not Japan’s 100 V system, so repaired power hardware and step-down equipment must be treated seriously. A used X68000 bought through eBay Australia, Gumtree or a local retro-computing group may also arrive with a modified PSU, an English keyboard or media prepared by an emulator user.

Testing, preservation and release

Testing should cover more than a clean directory. Include empty directories, names containing spaces, long Japanese names, duplicate case variants, read-only files, full disks, missing volumes and paths that end at the root. Test copy failures by filling a destination or removing media while an operation is in progress. These cases reveal whether the interface returns to a usable state after an error.

Keep the core source separate from compiler-specific startup code, screen routines and DOS bindings. A small build script can produce an executable for an emulator, while a second target packages the same binary for a physical CompactFlash card or hard-disk image. Record the compiler version, memory model, required libraries and expected console mode in a plain text README.

Preservation has legal and practical boundaries in Australia. The Copyright Act 1968 can affect the redistribution of commercial software, ROM images and documentation, even when the hardware is decades old. Sharing original source, patches, build instructions and user-created test data is generally easier to justify than bundling copyrighted disks. A release should identify which files are authored by the project and which must be obtained separately.

Hardware experiments also benefit from clear documentation. If a future version supports a pointing device or custom input board, the light-pen interface guide illustrates the value of recording wiring, timing and testing details rather than publishing only a finished photograph. That approach helps Australian hobbyists maintain machines far from specialist repair shops and makes the work reproducible for the wider X68000 community.

A useful first release is modest: browse two paths, create directories, copy files, rename entries, delete with confirmation, and display accurate errors. Once those functions are dependable, add sorting, a viewer and optional direct-screen rendering. Publish the source with a known-good disk image and test directory, then invite the community to run it on both emulators and original systems. A Human68k file manager becomes valuable when it is easy to build, safe to use and documented well enough to survive the next generation of hardware repairs.