# DVX Shell Applications

DXE3 application modules for the DVX Shell. Each app is a `.app` file
(DXE3 shared object) in a subdirectory under `apps/`. The Program
Manager scans this directory at startup and displays all discovered
apps as launchable icons.


## DXE App Contract

Every app exports two symbols:

* `appDescriptor` (`AppDescriptorT`) -- name, hasMainLoop, multiInstance, stackSize, priority
* `appMain` (`int appMain(DxeAppContextT *)`) -- entry point

Optional: `appShutdown` (`void appShutdown(void)`) -- called during
graceful shutdown.

### Callback-Only Apps (hasMainLoop = false)

`appMain()` creates windows, registers callbacks, and returns 0. The
shell drives everything through event callbacks. No dedicated task or
stack is allocated. Lifecycle ends when the last window closes.

### Main-Loop Apps (hasMainLoop = true)

A cooperative task is created for the app. `appMain()` runs its own
loop calling `tsYield()` to share CPU. Lifecycle ends when `appMain()`
returns.


## Applications

### Program Manager (progman)

| | |
|---|---|
| File | `apps/progman/progman.app` |
| Type | Callback-only |
| Multi-instance | No |

The desktop app. Scans `apps/` recursively for `.app` files and
displays them in a grid. Double-click or Enter launches an app.
Includes a Help menu with system information dialog and About box.

Registers with `shellRegisterDesktopUpdate()` to refresh when apps
are loaded, crash, or terminate.

Widget headers used: `widgetBox.h`, `widgetButton.h`, `widgetLabel.h`,
`widgetStatusBar.h`, `widgetTextInput.h`.

### Notepad (notepad)

| | |
|---|---|
| File | `apps/notepad/notepad.app` |
| Type | Callback-only |
| Multi-instance | Yes |

Text editor with File menu (New, Open, Save, Save As) and Edit menu
(Cut, Copy, Paste, Select All). Uses the TextArea widget for all
editing. 32KB text buffer limit. Tracks dirty state for save prompts.
Keyboard accelerators for all menu commands.

Widget headers used: `widgetTextInput.h`.

### Clock (clock)

| | |
|---|---|
| File | `apps/clock/clock.app` |
| Type | Main-loop |
| Multi-instance | Yes |

Digital clock display showing time and date. Demonstrates the main-loop
app pattern -- polls the system clock every second and invalidates the
window to trigger a repaint. Uses raw `onPaint` callbacks (no widgets)
to draw centered text.

Widget headers used: none (raw paint callbacks).

### DVX Demo (dvxdemo)

| | |
|---|---|
| File | `apps/dvxdemo/dvxdemo.app` |
| Type | Callback-only |
| Multi-instance | No |

Comprehensive widget system showcase. Opens multiple windows
demonstrating 31 of the 32 widget types (all except Timer):

* Main window: raw paint callbacks (gradients, patterns, text)
* Widget demo: form widgets (TextInput, Checkbox, Radio, ListBox)
* Controls window: TabControl with tabs for advanced widgets
  (Dropdown, ProgressBar, Slider, Spinner, TreeView, ListView,
  ScrollPane, Toolbar, Canvas, Splitter, Image)
* Terminal window: AnsiTerm widget

Widget headers used: 25 of the 26 widget headers (all except widgetTimer.h).

Resources: `logo.bmp`, `new.bmp`, `open.bmp`, `sample.bmp`, `save.bmp`.

### Control Panel (cpanel)

| | |
|---|---|
| File | `apps/cpanel/cpanel.app` |
| Type | Callback-only |
| Multi-instance | No |

System configuration with four tabs:

* **Mouse** -- scroll direction, double-click speed, acceleration
* **Colors** -- all 20 system colors with live preview, theme load/save
* **Desktop** -- wallpaper image selection and display mode
* **Video** -- resolution and color depth switching

Changes preview live. OK saves to `DVX.INI`, Cancel reverts to the
state captured when the control panel was opened.

Widget headers used: `widgetBox.h`, `widgetButton.h`, `widgetCanvas.h`,
`widgetDropdown.h`, `widgetLabel.h`, `widgetListBox.h`, `widgetSlider.h`,
`widgetSpacer.h`, `widgetTabControl.h`.

### Image Viewer (imgview)

| | |
|---|---|
| File | `apps/imgview/imgview.app` |
| Type | Callback-only |
| Multi-instance | Yes |

Displays BMP, PNG, JPEG, and GIF images. The image is scaled to fit
the window while preserving aspect ratio. Resize the window to zoom.
Open files via the File menu or by launching with Run in the Task
Manager.

Widget headers used: none (raw paint callbacks with `dvxLoadImage()`).


## Build

```
make            # builds all 6 app DXE modules
make clean      # removes objects and app files
```

Each app compiles to a single `.o`, then is packaged via `dxe3gen`
into a `.app` DXE exporting `appDescriptor` and `appMain` (plus
`appShutdown` for clock).

Output goes to `bin/apps/<name>/<name>.app`.


## Files

```
apps/
  Makefile           top-level build for all apps
  progman/
    progman.c        Program Manager
  notepad/
    notepad.c        text editor
  clock/
    clock.c          digital clock
  dvxdemo/
    dvxdemo.c        widget demo
    logo.bmp         DVX logo bitmap
    new.bmp          toolbar icon
    open.bmp         toolbar icon
    sample.bmp       sample image
    save.bmp         toolbar icon
  cpanel/
    cpanel.c         control panel
  imgview/
    imgview.c        image viewer
```