# The MIT License (MIT)
#
# Copyright (C) 2026 Scott Duensing
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
# deal in the Software without restriction, including without limitation the
# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
# sell copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
# IN THE SOFTWARE.

.section Libraries
.topic lib.taskmgr
.title Task Manager
.toc 0 Task Manager
.index Task Manager
.index shellTaskMgrOpen
.index shellTaskMgrRefresh

.h1 Task Manager

System-level task manager for DVX. Displays all running applications with a six-column ListView (Name, Title, File, Type, Memory, Status) and exposes Switch To, End Task, and Run... operations. Always accessible via Ctrl+Esc regardless of which application is focused. Persists independently of the desktop app (Program Manager).

Header: taskmgr/shellTaskMgr.h

Loaded as: bin/libs/taskmgr.lib

.h2 Integration

The task manager is a shell-level library, not a regular DXE app. At DXE load time a GCC constructor function registers the Task Manager with the shell by setting the shellCtrlEscFn function pointer (declared extern in dvxshell/shellApp.h). The shell invokes shellCtrlEscFn on every Ctrl+Esc keystroke; if taskmgr.lib is not loaded the pointer stays NULL and Ctrl+Esc does nothing.

The Task Manager owns its window on behalf of the shell itself (appId = 0), not any running app, which is why it survives when the desktop app terminates. It registers shellTaskMgrRefresh with shellRegisterDesktopUpdate so the list refreshes live as apps load, reap, or crash.

.h2 Integration with libtasks

The Task Manager reads from the shell's app slot table (shellGetApp, shellAppSlotCount, shellRunningAppCount) rather than from the libtasks scheduler directly. Each ShellAppT slot carries its cooperative task ID when hasMainLoop is true; End Task calls shellForceKillApp, which in turn calls tsKill on that task ID (for main-loop apps) after destroying the app's windows.

.h2 Features

.list
.item Six-column ListView showing Name, Title, File, Type (Task or Callback), Memory (from dvxMemGetAppUsage), and Status for every running app.
.item Switch To button (Alt+S): raises and focuses the selected app's topmost window, restoring it if minimized. Also triggered by double-clicking a row.
.item End Task button (Alt+E): force-kills the selected app via shellForceKillApp.
.item Run... button (Alt+R): opens a file dialog to browse for and launch a .app file.
.item Status bar showing running app count plus total and used system memory.
.item Single-instance: reopening the Task Manager while it is already visible raises and focuses the existing window rather than creating a new one.
.endlist

.h2 shellTaskMgrOpen

Open the Task Manager window, or raise it to the front if already open.

.code
void shellTaskMgrOpen(AppContextT *ctx);
.endcode

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context (from dvxInit). Required for window creation, stack manipulation, and registering the desktop-update callback.
.endtable

Called by the shell's global Ctrl+Esc handler via the shellCtrlEscFn hook.

.h2 shellTaskMgrRefresh

Rebuild the task list display from the current shell app slot table and refresh the status bar. Registered with shellRegisterDesktopUpdate at open time so it is invoked whenever the shell detects app state changes.

.code
void shellTaskMgrRefresh(void);
.endcode

Takes no parameters. Safe to call even if the Task Manager window is not currently open (the call is a no-op in that case).
