wdesk¶

the desktop on the resident window-manager kernel
NAME
    wdesk - the desktop on the resident window-manager kernel

SYNOPSIS
    wdesk [-r]

DESCRIPTION
    A desktop whose window manager lives in the OPERATING SYSTEM, not in
    the program. The kernel (os/wmkernel_body.asm, folded into the OS
    image) holds the window records and runs the event loop; it is
    reached through syscalls right after SYS_EXEC -- SYS_WKINIT ($2027),
    SYS_WKOPEN ($202A), SYS_WKREPAINT ($202D), SYS_WKRUN ($2030),
    SYS_WKSAVE ($2033), SYS_WKLOAD ($2036), SYS_WKPATH ($2039) -- and is
    resident from boot, so wdesk itself is only a thin LAUNCHER: it
    records the SHAPES scene into a card-resident command list, opens
    its windows, points the launch key at paint, and hands over to
    SYS_WKRUN.

    THE POINT: the TPA holds one program, so launching an application
    replaces the desktop in memory (System-1 style, see man desk). With
    `desk`, that destroys the window manager -- the app must re-exec
    desk from scratch. With wdesk the manager is in the OS: press 'l',
    paint loads OVER wdesk, and when you quit paint it calls SYS_WKRUN
    (it was launched with -w) and the desktop reappears with every
    window exactly where it was. The records survived in the OS, the
    SHAPES picture survived on the card (CLRUN replays it), and nothing
    was reloaded.

    THE MENU BAR (the white strip across the top, drawn by wdesk itself,
    not the kernel):

        DESK      PAINT      CLOSE      QUIT

    The desktop and its windows are the KERNEL's; the menu bar is the
    CLIENT's. wdesk drives the kernel one event at a time (SYS_WKEVENT):
    the kernel handles the window mechanics and hands wdesk the keys it
    does not own AND any mouse click in the bar's top rows (with the
    cursor column, via SYS_WKARG) -- wdesk maps the column to a word.

    CLICK a bar word, or press its letter -- both do the same:

    PAINT  or  L      launch paint OVER wdesk. paint runs in the same
                      TPA; the kernel keeps the windows alive. Quitting
                      paint (it was launched with -w) re-runs "wdesk -r",
                      which redraws the SAME windows and this menu bar --
                      the desktop survives the launch.
    CLOSE  or  C      close the top (focused) window (SYS_WKCLOSE)
    QUIT   or  Q      leave the desktop for the shell (Ctrl-D also quits)

    The FOCUSED window is the top one: WHITE title bar, the others GREY.

    TAB               cycle focus: raise the bottom window to the top
    arrow keys        move the focused (top) window 8 px
    mouse             press ANY window to raise and focus it; hold and
                      drag to move it, release to place it. Press the
                      small black CLOSE BOX at the left of a title bar
                      to close that window. Xterm SGR reports; see
                      man paint, MOUSE.

OPTIONS
    -r  RESUME: the windows are already in the resident kernel (a
        launched app is returning), so skip init and just redraw. Not
        for interactive use -- it is how paint -w brings the desktop
        back.

WINDOWS
    SHAPES   a demo scene recorded into a card list (the card replays it).
    TERM     a real terminal: a command you type runs and its OUTPUT appears
             IN the window. While TERM is the focused (top) window it owns the
             WHOLE keyboard -- so l, c and q TYPE, they do not fire the menu
             (the menu bar is still clickable). Type a command and:

                 ENTER       run it. The shell runs the command (any /bin
                             program, a builtin like pwd) with its stdout
                             routed into this window; when it finishes the
                             desktop returns with the output on screen. Try
                             `pwd`, `dir`, `cat FILE`.
                 BACKSPACE   erase the last character of the line.

             How: wdesk arms the OS's OUTCH->window sink (SYS_WKSINK) at TERM's
             card list, writes a two-line script -- the command, then
             `run /bin/wdesk.bin -o` -- and hands it to the shell (SYS_RUNSH).
             The command's output records into the card list (which the kernel
             replays on repaint, so it needs no memory buffer); `wdesk -o`
             disarms the sink and repaints. The command itself is echoed to the
             serial console, not the window, so only its output shows here.

             v1 limits: each command clears the window first (no scrollback
             across commands yet), long lines and past-the-bottom output clip
             (no wrap/scroll), and a GUI app (paint) is better launched from
             the menu or FILES than typed here.
    FILES    a browser for the current directory, drawn by wdesk itself
             inside the window (the kernel gives the rect via SYS_WKGET;
             the client draws the text and clips it to the window body).
             The listing shows while FILES is the focused (top) window.

             With FILES focused (click it to the top, or TAB to it):

                 n  or  p    move the selection down / up one entry (the
                             selected row is highlighted yellow)
                 ENTER       open the selected entry --
                               a directory  -> navigate into it and relist
                                               (".." goes up; ".", up too)
                               a .BIN file   -> launch it (as paint does,
                                               with -w so it resumes here)
                               any other file is skipped for now

             The whole browser is the CLIENT's: the kernel only hands over
             the window rect and the keys FILES does not own. Navigation
             re-reads the directory into wdesk's own cache; the SHAPES
             card list is untouched, so both windows keep their content.

             ENTER on a .P8I image opens it in the VIEW window (below).
    VIEW     a picture window. It is not there at first; opening a .P8I
             from FILES opens VIEW sized to the image and streams the
             picture into it (one card BLIT per row, the desk viewer moved
             into a kernel window). Opening another .P8I while VIEW is up
             re-fronts the same window (the kernel's SYS_WKRAISE) and shows
             the new picture. CLOSE (the menu, the C key, or the title-bar
             box) removes it. The image is re-streamed from disk on each
             repaint -- there is no framebuffer -- so dragging VIEW is slow.

    Windows are addressed by the FIRST LETTER of their title (S/T/F/V), not
    by position: the kernel physically reorders the window records when one
    is raised, so wdesk reads the focused window's record and dispatches on
    its title -- which is why focus, content and keys always follow the
    right window.

NOTES
    This is the resident-kernel rung of the window-system ladder
    (docs/p8x-wm-design.md). The window manager lives in the OS; the rich
    UI -- the menu bar and the TERM, FILES and VIEW windows -- lives here in
    the CLIENT, so the two grow independently. The older standalone `desk`
    keeps its whole GUI inside one program (WM and app share the TPA, so
    launching an app destroys the desktop); it is unchanged and still a
    useful reference, but wdesk is the successor built on the resident
    kernel. Boot is unchanged: monitor, B, the shell -- the GUI is opt-in
    by command.

    A program launched by the kernel gets the arguments in the SYS_WKPATH
    string. paint understands -w (resume the resident desktop on quit)
    as well as -d (re-exec desk). A program that ignores both simply
    exits to the shell; type wdesk to return.

SEE ALSO
    desk, paint, gl