Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
177 lines (124 loc) · 4.97 KB

ARCHITECTURE.md

File metadata and controls

177 lines (124 loc) · 4.97 KB

TalkEd Architecture

Overview

TalkEd is organized around a single Delphi 7 VCL application with a form-driven UI and one main domain unit for TLK file parsing and persistence.

The architecture is simple by modern standards:

  • one project entrypoint,
  • one main orchestration form,
  • several modal forms for focused operations,
  • one TLK file handler that owns file IO and in-memory entries,
  • a few utility units for string and grid support.

Startup Flow

TLKEdit.dpr performs the following high-level sequence:

  1. initialize the VCL application,
  2. create the main form,
  3. create the search, entry, language, confirm-delete, and pad forms,
  4. inspect the first command-line argument,
  5. if that argument exists and ends in .tlk, call MainForm.LoadFile(...),
  6. run the application message loop.

This means TalkEd supports both normal GUI startup and a file-associated launch flow.

Main UI Controller

UMainForm.pas is the operational center of the app.

Responsibilities include:

  • loading and saving TLK files,
  • managing interval-based grid display,
  • dispatching search and edit actions,
  • prompting before destructive or state-losing actions,
  • reflecting current selection into the detail memo,
  • controlling auxiliary modal forms.

Important behaviors:

  • large files are intentionally displayed by interval to limit memory cost,
  • the app tracks unsaved modification state through the TLK handler,
  • delete operations reindex following StrRef values,
  • append and pad workflows can expand the talk table significantly.

TLK Domain Layer

UTLKFile.pas holds the core model and serialization logic.

TTLKString

Represents one TLK entry, including:

  • entry flags,
  • sound resref,
  • volume variance,
  • pitch variance,
  • string offset,
  • string size,
  • sound length,
  • numeric StrRef,
  • string text,
  • a boolean marking entries created or modified in-session.

TStringData and TStringDataList

Entries are stored in a custom doubly linked list rather than a Delphi container class.

Implications:

  • traversal is sequential,
  • many workflows scan entries linearly,
  • edits preserve the project’s original data structure assumptions,
  • delete operations must maintain list integrity and StrRef reindexing.

TTLKFileHandler

Owns:

  • TLK header fields,
  • string count,
  • entry-table offset,
  • filename and open-state tracking,
  • dirty/modified state,
  • add/replace/delete/new/load/save operations.

Notable serialization behavior:

  • validates the TLK file signature and version V3.0,
  • reads and writes the TLK header and string data table,
  • handles long strings by reading and writing in segments rather than assuming a single 4096-byte buffer is enough,
  • uses entry text length as the stored string size,
  • marks new or modified entries as custom.

UI Forms

USearchForm.pas

Encapsulates search criteria state and input validation.

Supported search modes include:

  • exact text,
  • substring text,
  • whole-word style matching,
  • case-sensitive matching,
  • negated matching,
  • sound-entry filtering,
  • non-blank filtering,
  • new-entry filtering,
  • range-constrained filtering.

UEntryForm.pas

Used for both add and edit workflows.

Captures:

  • entry text,
  • text-present flag,
  • sound-present flag,
  • sound-length-present flag,
  • sound resref,
  • volume variance,
  • pitch variance,
  • sound length.

ULanguageForm.pas

Small modal form for editing the TLK language id.

UPadForm.pas

Collects a target StrRef and pads the talk table with blank entries up to that point.

UConfirmDelete.pas

Provides a dedicated delete confirmation dialog before reindexing the table.

Utility Units

  • StoffeUtils.pas: string helpers such as substitution and substring helpers.
  • UStrTok.pas: tokenizer support used by word-search logic.
  • modgrids.pas: grid-related helpers.

Data and Control Flow

The normal editing loop looks like this:

  1. TMainForm asks TTLKFileHandler to load a file.
  2. The file handler parses the header and populates the linked list.
  3. The main form renders an interval of entries into the grid.
  4. Auxiliary forms collect user input for edits, searches, or metadata changes.
  5. The main form translates those form values into TTLKString updates.
  6. The file handler marks the model modified.
  7. The main form re-renders the current interval or search results.
  8. Save writes the linked-list contents back to a new TLK binary.

Architectural Constraints

  • Form creation is eager rather than on-demand.
  • Units are tightly coupled through globals and shared forms.
  • The TLK model is mutable and UI-driven.
  • There is no test seam or dependency-injection layer.
  • Manual runtime verification remains the realistic validation strategy.

Change Risk Areas

Extra care is required when modifying:

  • UTLKFile.pas long-string serialization,
  • delete and append operations that affect StrRef ordering,
  • any code path that assumes the linked list cursor state,
  • save/load behavior for sound resrefs and lengths,
  • search behavior where flags interact.