Home /Modules/guidoc/GUIDOC.md

GUIDOC.md

lib/guidoc/GUIDOC.md · 314 line(s) · markdown

guidoc — the document GUI, in white

A document editor with menus, tabs, an editor, and load/save, built on a GUI document listener: each tab holds a standing document with its own dynamic observer, and a white GUI listener admitted to that observer keeps the screen in step with the document, telling edits made through the GUI apart from edits made by someone else.

Quick start

sleela run lib/guidoc/guidoc.sleela                  # build, check, print the screen
SLEELA_GUIDOC_OPEN=notes.txt sleela run lib/guidoc/guidoc.sleela     # open a file first
SLEELA_GUIDOC_PLAN=1 sleela run lib/guidoc/guidoc.sleela             # also print the mount plan
sleela run lib/guidoc/guidoc-demo.sleela             # 275 self-checks, headless
bash test-suites/test-guidoc.sh                      # the release gate (CI runs this)

The launcher ends with GUIDOC READY 1.0.0 certified (...) or GUIDOC NOT READY: .... (SLeeLa 3.0 main cannot set an exit status and sleela run treats extra arguments as source files, so the launcher takes its file from the environment and scripts match the final line.)

What it looks like (white)

 SLeeLa Document Editor - /home/me/notes.txt*                      bg #F7F8FA  ink #16202C
┌──────────────────────────────────────────────────────────────────────────┐
│ File  Edit  View  Help                                    chrome #FFFFFF │
├──────────────────────────────────────────────────────────────────────────┤
│ [ notes.txt* ] [ second.txt ] [ + ]                      active tab: accent #1F6FEB │
├────┬─────────────────────────────────────────────────────────────────────┤
│  1 │ alpha                                              surface #FFFFFF  │
│  2 │ gamma            ◀ selected row: accent #1F6FEB, white text          │
│  3 │ tail                                                                │
├────┴─────────────────────────────────────────────────────────────────────┤
│ [ text for the next edit                                               ] │
├──────────────────────────────────────────────────────────────────────────┤
│ inserted line 3        Ln 3 of 3  rev 6        White | in step at rev 6  │
└──────────────────────────────────────────────────────────────────────────┘

Every colour comes from the White flavor of the standard UI themes (lib/ui SLThemeFlavor.white()) through SLGuiDocWhite; unsaved changes show in the warning ink, external changes in the status line, errors in the danger ink.

The XML document

gui-document.xml describes the GUI and gui-document.xsd is its schema:

ElementDescribes
<window title theme>title and theme flavor (white, blue, gray, black; this document is white)
<commands><command id handler confirmsDiscard>every command and the SLGuiDocApp method that runs it; commands that can discard work set confirmsDiscard
<menus><menu><item id label command accelerator enabledWhen>the menu bar. command must name a declared command (a keyref); enabledWhen is one of always hasTab dirty editable selectionEditable multipleTabs
<tabs maxTabs dirtyMarker newTabTitle>the tab strip (at most 14, echoing the 1..14 watch bound of lib/gui)
<editor rows lineNumbers readOnlyWhenUnsplit>the editor
<fileDialog sidecarSuffix maxLines maxBytes>load and save limits
<listener port repaintOn flagExternal>the GUI document listener
<keys><key accelerator scope action>modal keys: Enter and Esc while a dialog (dialog.ok, dialog.cancel) or a menu (menu.close) is open
<lock choiceEdits>whether an editor's choice session keeps (keep) or reverts (revert) its edits
<readiness status release>the readiness claim and the release version

Commands also carry lockPolicy (allowed · blocked · choice) and menu items may be toggles (toggle="lock|choice" with an activeLabel); enabledWhen gains admin, choiceReady and hasLines.

SLGuiDocSpec.standard() is the executable copy; the GUI is built from it. SLeeLa cannot parse XML at run time (no string access), so tools/validate_gui_document.py keeps the two together: it validates the XML against the schema (xmllint), applies the rules the schema cannot express (declared commands, unique accelerators, no orphan commands, discarding commands must confirm, every handler exists in SLGuiDocApp, theme is white) and fails if the XML and standard() differ.

Commands

MenuItemAcceleratorEnabled whenDoes
FileNewCtrl+Nalwaysa new untitled tab
FileOpen...Ctrl+Oalwaysopen dialog; opens in a new tab, or switches to the tab that has it
FileSaveCtrl+Sdirtysaves to the tab's path (Save As if it has none)
FileSave As...Ctrl+Shift+ShasTabsave dialog
FileClose TabCtrl+WhasTabasks first if there are unsaved changes
FileQuitCtrl+Qalwaysasks first if any tab has unsaved changes
EditInsert LineCtrl+Ieditableinserts the entry text after the selected line (or at the end)
EditReplace LineCtrl+RselectionEditablereplaces the selected line
EditDelete LineCtrl+DselectionEditabledeletes the selected line
EditEdit LineF2selectionEditablecopies the selected line into the entry box, to change and Replace
ViewNext / Previous TabCtrl+Tab / Ctrl+Shift+TabmultipleTabscycles tabs
ViewPrevious / Next LineUp / DownhasLinesmoves the selection; the editor scrolls to keep it in view
ViewPage Up / Page DownPageUp / PageDownhasLinesmoves the selection a page (rows - 1)
SystemLock System / Unlock SystemCtrl+Ladminthe system lock (below)
SystemEditor's Choice / End Editor's ChoiceCtrl+EchoiceReadyan admin session on one tab (below)
HelpAboutF1alwaysstatus line

While a dialog is open, every other command is refused and the menus are disabled.

Wiring

Everything a window can tell the GUI is one of five events, and SLGuiDocHost.event(app, kind, id, value) is the single entry point for them:

EventCallWhat it does
press idapp.click(id)a widget was activated: menu, menu item, tab, row, button, dialog button
type id valueapp.type(id, value)the user typed into an entry (entry, dlg-path)
key chordapp.accelerate(chord)Ctrl+S, Up, F2, ... and Enter / Esc while a dialog or menu is open
closeapp.requestClose()the window close button: cancels an open dialog, else Quit (which asks first if work is unsaved)
tickapp.refresh()a turn of the host loop: repaint if a document changed outside the GUI

Every widget with a behavior carries a command; the gate's wiring check proves each one reaches a handler. A widget that is hidden or disabled cannot be pressed.

Every setting in the XML changes behavior, and guidoc-demo proves each one by changing it and watching:

XMLActs on
window title/themethe window title; the GUI refuses to build in a flavor it does not draw (white)
command handler, menu itemthe dispatch table and the menu; the validator checks each handler exists
command confirmsDiscardwhether Close Tab and Quit ask before discarding unsaved work (setConfirms)
command lockPolicywhat the system lock refuses
item accelerator, enabledWhen, togglekey chords, whether an item is enabled, its on/off label
tabs maxTabs/dirtyMarker/newTabTitlethe tab limit, the *, the name of a new tab
editor rows/lineNumbers/readOnlyWhenUnsplitrows shown and the scroll window, the gutter, whether unsplit files lock
fileDialog maxLines/maxBytes/sidecarSuffixload and save limits and the sidecar folder (applySettings() after a change)
listener port/flagExternalthe listener's port name; whether an outside change is flagged or only counted
keysEnter / Esc in dialogs and menus
lock choiceEditswhether an editor's choice session keeps or reverts its edits
readinessthe certified/draft label and the release shown by About and the launcher

The system lock and editor's choice

Lock System (admin only) disallows new content. Editor's Choice (admin only, while locked) lets the admin edit one document anyway, with no lasting consequence for that document or for the system.

What the lock does

Each command declares a lockPolicy in the XML:

PolicyCommandsWhile locked
allowedSave, Close Tab, Quit, Next/Previous Tab, Lock/Unlock, Editor's Choice, Aboutrun normally (Save writes an existing file; nothing is added)
blockedNew, Open, Save Asrefused, no exception: a new document or a new file would be new content
choiceInsert, Replace, Delete Linerefused unless the active tab has an editor's choice session

The menu items, the + button and the entry box are disabled to match, and the status shows LOCKED in the lock ink. The lock is enforced below the menu too: SLGuiDocTab refuses edits, and locking freezes each tab's observer (SLDocumentObserver.freeze()), so an outside writer or a module proposal is refused as well. Delete is under the lock because the lock freezes the document; change its policy to allowed in the XML (and standard()) if removing content should stay open. The validator insists that every content-adding command is not allowed, and that the lock and choice commands stay allowed so an admin can always unlock.

Editor's choice

Ready

The GUI is ready only after it has proved itself. configure() builds it; start() runs twelve named self-checks (SLGuiDocReady):

spec · white-theme · widget-tree (node count equals what the spec implies) · commands-handled (every spec command has a handler) · menu-items-bound (every item exists and is bound to its command) · accelerators-live · file-layer · listener-port · wiring (every widget that carries a command, and every modal key, reaches a handler) · lock-policy (no content-adding command is allowed while locked; the lock commands stay allowed; it starts unlocked) · first-paint · no-open-dialog

StateMeaning
createdbuilt, not checked: every command, click and accelerator is refused
checkingthe self-checks are running
readyevery check passed; subscribers are notified
faileda check failed; the first failure is kept; nothing is notified; start() can be retried once fixed

Like a document-ready event, subscribers register by name with whenReady() (before or after) and take a one-shot latch with takeReady(); a failed gate never fires one. A gate with no checks, or with more than 24, does not pass.

The readiness claim in the XML

<readiness status="draft|ready" release="1.0.0"/> is a claim, and tools/validate_gui_document.py --gate verifies it by running guidoc-demo: no failed check, a READY lifecycle with zero failures, and coverage - every command in the XML run at least once and every menu item clicked at least once (COVERAGE command|item <id> <n> lines printed by the demo). A document that claims ready while the gate fails is INVALID; --require-ready also demands the claim. status="ready" here means exactly that, and no more.

Host and launcher

The classes

ClassRole
SLGuiDocSpecthe spec (validated as added), mirror of the XML
SLGuiDocWhitethe white look: a style for every role
SLGuiDocFileload and save
SLGuiDocListenerthe GUI document listener; nested Responder is an observer module
SLGuiDocTabone open document: its observer, its listener, path, dirty state, selection, scroll
SLGuiDocViewthe widget tree (84 nodes): tag, text, style, visible, enabled, command; press latches
SLGuiDocAppthe controller: builds the view from the spec, runs commands, dialogs and tabs, repaints; start() runs the ready gate; counts coverage
SLGuiDocReadythe ready lifecycle and gate (named checks, one-shot subscribers)
SLGuiDocHostthe host side: text outline and mount plan
guidoc.sleelathe launcher
guidoc-demo.sleela275 self-checks and the coverage sweep

The GUI document listener

SLGuiDocListener.Responder is a drop-in observer module admitted to each tab's observer, so it has the full listener lifecycle (pause, resume, alter, replace, reinstate). Each change latches a repaint. A change whose source is not gui is an external change: it is counted, named in the status line (changed by alice (1 external change(s))) in the warning ink, and stays flagged until the user acknowledges it by selecting a line or editing. A host loop calls app.refresh() after anything outside the GUI may have changed a document.

Load and save

Save codeMeaningLoad codeMeaning
0ok0exact lines
1bad path10opened unsplit (read-only)
2cannot write1bad path
3cannot replace4cannot open / not found
4cannot write sidecar5too many lines
6too many lines7too large
9read-only tab8target not empty

Honest limits

Release