258 lines
8.3 KiB
TypeScript
258 lines
8.3 KiB
TypeScript
// SPDX-License-Identifier: GPL-3.0-or-later
|
|
// Copyright (C) 2026 ZiroEDA and contributors.
|
|
// Portions derived from KiCad, copyright The KiCad Developers. See NOTICE.md.
|
|
/**
|
|
* `include/kiway.h`, `common/kiway.cpp`: KIWAY, the way between the frames of
|
|
* one project.
|
|
*
|
|
* Upstream KIWAY loads the kiface DSOs and creates every KIWAY_PLAYER window
|
|
* itself; here the program does both - an editor is a view it mounts, and the
|
|
* project manager is the page every editor goes home to - so the program hands
|
|
* KIWAY a {@link KIWAY_PROGRAM} for those, and KIWAY keeps the rest: which
|
|
* players are alive, and the mail between them.
|
|
*
|
|
* One difference follows from mounting. `KIFACE::CreateKiWindow` returns the
|
|
* frame; a mounted view registers its player a render later
|
|
* ({@link KIWAY.SetPlayerFrame}). Mail sent to a player that {@link KIWAY.Player}
|
|
* has asked the program to create is held until it registers, which is what
|
|
* upstream's synchronous creation gives its callers for free
|
|
* (`Player( FRAME_FOOTPRINT_EDITOR, true )` then `ExpressMail( ..., MAIL_FP_EDIT )`).
|
|
*/
|
|
import { FRAME_T } from './frame_type.js';
|
|
import type { KIWAY_PLAYER } from './kiway_player.js';
|
|
import { KIWAY_MAIL_EVENT, type MAIL_PAYLOAD } from './kiway_mail.js';
|
|
import type { MAIL_T } from './mail_type.js';
|
|
import type { wxEvent } from '@ziroeda/wx/wx_event.js';
|
|
import type { KIFACE_ADDR_ID } from '@ziroeda/include/kiface_ids.js';
|
|
|
|
/**
|
|
* `struct KIFACE` (kiway.h:155): what one kiface offers the others. Here only
|
|
* `IfaceOrAddress` - the program mounts the frames itself, so `CreateKiWindow`
|
|
* and `OnKifaceStart` live in each kiface's own module.
|
|
*/
|
|
export interface KIFACE {
|
|
/**
|
|
* `IfaceOrAddress( aDataId )`: the object or function a KIFACE_ADDR_ID names,
|
|
* cast by the caller into its known type; null for an id the face does not serve.
|
|
*/
|
|
IfaceOrAddress(aDataId: KIFACE_ADDR_ID): unknown;
|
|
}
|
|
|
|
/** `KIWAY::FACE_T`: the kiface DSOs a frame type belongs to. */
|
|
export enum FACE_T {
|
|
FACE_SCH, ///< eeschema DSO
|
|
FACE_PCB, ///< pcbnew DSO
|
|
FACE_CVPCB,
|
|
FACE_GERBVIEW,
|
|
FACE_PL_EDITOR,
|
|
FACE_PCB_CALCULATOR,
|
|
FACE_BMP2CMP,
|
|
FACE_PYTHON,
|
|
|
|
KIWAY_FACE_COUNT,
|
|
}
|
|
|
|
/** What the program does for KIWAY: the kifaces' windows and the top frame. */
|
|
export interface KIWAY_PROGRAM {
|
|
/** `KIWAY::OnKiCadExit()`: leave the suite (here, go back to the project manager). */
|
|
OnKiCadExit(): void;
|
|
|
|
/**
|
|
* `KIWAY::Player( aFrameType, true )` + `showFrame()`: open or raise that
|
|
* editor. False where the program has no such player.
|
|
*/
|
|
Player(aFrameType: FRAME_T): boolean;
|
|
|
|
/**
|
|
* `Kiway().GetTop()` is `KICAD_MAIN_FRAME_T`: whether a project manager
|
|
* exists to switch to. False is upstream's stand-alone mode.
|
|
*/
|
|
HasProjectManager(): boolean;
|
|
|
|
/** `showFrame( Kiway().GetTop() )`: raise the project manager. */
|
|
ShowProjectManager(): void;
|
|
|
|
/**
|
|
* `KIFACE::CreateKiWindow( parent, aDialogId, &Kiway() )` for the dialogs
|
|
* another kiface owns - the library tables, Configure Paths. False when that
|
|
* kiface is not available, which upstream also swallows.
|
|
*/
|
|
CreateKiWindow(aClassId: FRAME_T): boolean;
|
|
|
|
/**
|
|
* `KIWAY::KiFACE( aFaceId )`: the kiface of that FACE_T, or null where the
|
|
* program has none (upstream's failed DSO load). Optional: a program with no
|
|
* kiface to offer leaves it out.
|
|
*/
|
|
KiFACE?(aFaceId: FACE_T): KIFACE | null;
|
|
}
|
|
|
|
export class KIWAY {
|
|
private readonly m_program: KIWAY_PROGRAM;
|
|
|
|
/** `m_playerFrameId`: the live player of each FRAME_T. */
|
|
private readonly m_playerFrame = new Map<FRAME_T, KIWAY_PLAYER>();
|
|
|
|
/** Mail for players the program is still creating, delivered when they register. */
|
|
private readonly m_pendingMail = new Map<FRAME_T, KIWAY_MAIL_EVENT[]>();
|
|
|
|
constructor(aProgram: KIWAY_PROGRAM) {
|
|
this.m_program = aProgram;
|
|
}
|
|
|
|
/**
|
|
* A simple mapping function which returns the FACE_T which is known to
|
|
* implement @a aFrameType; `FACE_T( -1 )` for none (kiway.cpp:345-386).
|
|
*/
|
|
static KifaceType(aFrameType: FRAME_T): FACE_T {
|
|
switch (aFrameType) {
|
|
case FRAME_T.FRAME_SCH:
|
|
case FRAME_T.FRAME_SCH_SYMBOL_EDITOR:
|
|
case FRAME_T.FRAME_SCH_VIEWER:
|
|
case FRAME_T.FRAME_SYMBOL_CHOOSER:
|
|
case FRAME_T.FRAME_SIMULATOR:
|
|
return FACE_T.FACE_SCH;
|
|
|
|
case FRAME_T.FRAME_PCB_EDITOR:
|
|
case FRAME_T.FRAME_FOOTPRINT_EDITOR:
|
|
case FRAME_T.FRAME_FOOTPRINT_VIEWER:
|
|
case FRAME_T.FRAME_FOOTPRINT_CHOOSER:
|
|
case FRAME_T.FRAME_FOOTPRINT_WIZARD:
|
|
case FRAME_T.FRAME_PCB_DISPLAY3D:
|
|
return FACE_T.FACE_PCB;
|
|
|
|
case FRAME_T.FRAME_CVPCB:
|
|
case FRAME_T.FRAME_CVPCB_DISPLAY:
|
|
return FACE_T.FACE_CVPCB;
|
|
|
|
case FRAME_T.FRAME_PYTHON:
|
|
return FACE_T.FACE_PYTHON;
|
|
|
|
case FRAME_T.FRAME_GERBER:
|
|
return FACE_T.FACE_GERBVIEW;
|
|
|
|
case FRAME_T.FRAME_PL_EDITOR:
|
|
return FACE_T.FACE_PL_EDITOR;
|
|
|
|
case FRAME_T.FRAME_CALC:
|
|
return FACE_T.FACE_PCB_CALCULATOR;
|
|
|
|
case FRAME_T.FRAME_BM2CMP:
|
|
return FACE_T.FACE_BMP2CMP;
|
|
|
|
default:
|
|
return -1 as FACE_T;
|
|
}
|
|
}
|
|
|
|
OnKiCadExit(): void {
|
|
this.m_program.OnKiCadExit();
|
|
}
|
|
|
|
/** `KiFACE( aFaceId, aDoLoad )` (kiway.cpp:213): null when that kiface is not available. */
|
|
KiFACE(aFaceId: FACE_T): KIFACE | null {
|
|
return this.m_program.KiFACE?.(aFaceId) ?? null;
|
|
}
|
|
|
|
/**
|
|
* `Player( aFrameType, true )` + `showFrame()`: open or raise that editor.
|
|
* A player not yet alive is being created from here on, so mail sent to it
|
|
* waits for it.
|
|
*/
|
|
Player(aFrameType: FRAME_T): boolean {
|
|
const shown = this.m_program.Player(aFrameType);
|
|
|
|
if (shown && !this.m_playerFrame.has(aFrameType) && !this.m_pendingMail.has(aFrameType))
|
|
this.m_pendingMail.set(aFrameType, []);
|
|
|
|
return shown;
|
|
}
|
|
|
|
HasProjectManager(): boolean {
|
|
return this.m_program.HasProjectManager();
|
|
}
|
|
|
|
ShowProjectManager(): void {
|
|
this.m_program.ShowProjectManager();
|
|
}
|
|
|
|
CreateKiWindow(aClassId: FRAME_T): boolean {
|
|
return this.m_program.CreateKiWindow(aClassId);
|
|
}
|
|
|
|
/** `GetPlayerFrame( aFrameType )`: the live player of that type, or null. */
|
|
/**
|
|
* `CommonSettingsChanged( aFlags )` (kiway.cpp:599): every open player hears it. The project
|
|
* manager's frame (`m_top`) is the program's, not a KIWAY_PLAYER here, and ENVVARS_CHANGED's
|
|
* library preload is the program's library loader; neither runs through this.
|
|
*/
|
|
CommonSettingsChanged(aFlags: number): void {
|
|
for (const frame of this.m_playerFrame.values()) frame.CommonSettingsChanged(aFlags);
|
|
}
|
|
|
|
GetPlayerFrame(aFrameType: FRAME_T): KIWAY_PLAYER | null {
|
|
return this.m_playerFrame.get(aFrameType) ?? null;
|
|
}
|
|
|
|
/**
|
|
* `m_playerFrameId[aFrameType].store( frame->GetId() )`, which upstream does
|
|
* as `CreateKiWindow` returns: the player is alive, and any mail held for it
|
|
* is delivered.
|
|
*/
|
|
SetPlayerFrame(aFrameType: FRAME_T, aFrame: KIWAY_PLAYER): void {
|
|
this.m_playerFrame.set(aFrameType, aFrame);
|
|
|
|
const pending = this.m_pendingMail.get(aFrameType);
|
|
this.m_pendingMail.delete(aFrameType);
|
|
|
|
for (const mail of pending ?? []) aFrame.ProcessEvent(mail);
|
|
}
|
|
|
|
/**
|
|
* Notify the KIWAY that a player frame is closing: `m_playerFrameId[aFrameType]
|
|
* = wxID_NONE`. Only the frame registered for that type is forgotten.
|
|
*/
|
|
PlayerDidClose(aFrameType: FRAME_T, aFrame?: KIWAY_PLAYER): void {
|
|
if (aFrame && this.m_playerFrame.get(aFrameType) !== aFrame) return;
|
|
|
|
this.m_playerFrame.delete(aFrameType);
|
|
this.m_pendingMail.delete(aFrameType);
|
|
}
|
|
|
|
/**
|
|
* Send `aPayload` to `aDestination` from `aSource`. The recipient receives it
|
|
* in `KIWAY_PLAYER::KiwayMailIn()`, and an answer comes back in `aPayload`.
|
|
*/
|
|
ExpressMail(
|
|
aDestination: FRAME_T,
|
|
aCommand: MAIL_T,
|
|
aPayload: MAIL_PAYLOAD,
|
|
aSource: unknown = null,
|
|
): void {
|
|
const mail = new KIWAY_MAIL_EVENT(aDestination, aCommand, aPayload, aSource);
|
|
|
|
this.ProcessEvent(mail);
|
|
}
|
|
|
|
/** `ProcessEvent`: route mail to its recipient, if it is alive. */
|
|
ProcessEvent(aEvent: wxEvent): boolean {
|
|
if (aEvent instanceof KIWAY_MAIL_EVENT) {
|
|
const dest = aEvent.Dest();
|
|
|
|
// see if recipient is alive
|
|
const alive = this.GetPlayerFrame(dest);
|
|
|
|
if (alive) return alive.ProcessEvent(aEvent);
|
|
|
|
const pending = this.m_pendingMail.get(dest);
|
|
|
|
if (pending) {
|
|
pending.push(aEvent);
|
|
return true;
|
|
}
|
|
}
|
|
|
|
return false;
|
|
}
|
|
}
|