9.2 KiB
The frame title, in all thirteen KiCad frames
Read out of KiCad 10.0.5 (/home/akshay/kicad-reference) on 2026-08-20, ahead of
deciding what a shared frameTitle() in designer/src/ui/useDocumentTitle.ts
has to satisfy. Nothing here is implemented yet; this is the reading.
Deferred on purpose. Akshay parked the migration on 2026-08-20 until the file manager lands, because the document half of every title is a file name and half the branches below turn on whether that file exists, is writable, or has ever been saved — questions only the file manager can answer. Doing it before then would mean inventing those predicates and redoing them after. This file is the reading, kept so the migration is a write-up rather than a re-read. The
[Read Only]/[Unsaved]predicates in note C are the ones that need the file manager; the em dash, the placeholders and the GetName/GetFullName split do not, and could move at any time.
The shape they share
Twelve of the thirteen end the same way:
title += wxT( " — " ) + <Frame Name>
SetTitle( title )
An em dash, U+2014, with one ASCII space either side. Never a hyphen. The document half in front of it is built by each frame, and that is where they differ.
The general form, where a frame uses all of it:
title = "*" if IsContentModified()
title += <document part>
title += " " + "[Read Only]" if the file is not writable
title += " " + "[Unsaved]" if the file does not exist yet
title += " — " + <Frame Name>
Note the [...] suffixes carry their own leading space (wxS( " " ) + _( "[Read Only]" )),
and * carries none — it butts straight against the name.
The table
| # | Frame | Frame Name | Document part | Placeholder when empty | * |
[Read Only] |
[Unsaved] |
Source |
|---|---|---|---|---|---|---|---|---|
| 1 | PCB Editor | PCB Editor |
fn.GetName() |
(none — see note A) | yes | yes | yes | pcbnew/pcb_edit_frame.cpp:2170-2195 |
| 2 | Schematic Editor | Schematic Editor |
fn.GetName() + [sheetPath] |
[no schematic loaded] |
yes | yes | yes | eeschema/sch_edit_frame.cpp:1819-1861 |
| 3 | Symbol Editor | Symbol Editor |
UnescapeString( LibId.Format() ), or m_reference |
[no symbol loaded] |
yes | [Read Only Library] |
— | eeschema/symbol_editor/symbol_editor.cpp:58-87 |
| 4 | Footprint Editor | Footprint Editor |
FPID.Format(), or reference (see note D) |
[no footprint loaded] |
yes | yes | yes | pcbnew/footprint_edit_frame.cpp:1080-1132 |
| 5 | Footprint Library Browser | Footprint Library Browser |
nickname — <full URI> |
[no library selected] |
— | — | — | pcbnew/footprint_viewer_frame.cpp:979-999 |
| 6 | Symbol Library Browser | Symbol Library Browser |
GetFullURI( row, true ) |
[no library selected] |
— | — | — | eeschema/symbol_viewer_frame.cpp:1043-1057 |
| 7 | SPICE Simulator | SPICE Simulator |
filename.GetName() |
(none — see note A) | yes | yes | yes | eeschema/sim/simulator_frame.cpp:316-343 |
| 8 | Drawing Sheet Editor | Drawing Sheet Editor |
file.GetName() |
[no drawing sheet loaded] |
yes | — | — | pagelayout_editor/pl_editor_frame.cpp:570-587 |
| 9 | Gerber Viewer | Gerber Viewer |
filename.GetFullName() + (with X2 attributes) |
(see note B) | — | — | — | gerbview/gerbview_frame.cpp:660-692 |
| 10 | Image Converter | Image Converter |
filename.GetFullName() |
(see note B) | — | — | — | bitmap2component/bitmap2cmp_frame.cpp:352-364 |
| 11 | KiCad (manager) | KiCad <major.minor> |
fn.GetName() |
[no project loaded] |
— | yes | — | kicad/kicad_manager_frame.cpp:1292-1312 |
| 12 | 3D Viewer (child) | — | 3D Viewer — <footprint name> |
— | — | — | — | pcbnew/footprint_viewer_frame.cpp:966, footprint_chooser_frame.cpp:392-398 |
| 13 | Calculator Tools | — | fixed string, no dash at all | — | — | — | — | pcb_calculator/pcb_calculator_frame.cpp:240 |
The details a shared helper must get right
A. GetName() versus GetFullName()
wxFileName::GetName() is the base name without the extension;
GetFullName() is base plus extension. Nine frames use GetName(). Exactly
two use GetFullName() — Gerber Viewer (:684) and the Image Converter
(:359) — so a helper that always strips the extension is wrong for both, and a
helper that never strips it is wrong for the other nine. It has to be a
parameter.
useDocumentTitle.ts:67-77's existing frameTitleName() implements GetName()
only, and is used by exactly one launcher (the drawing sheet editor).
B. The empty state is not uniform, and this is where ours is broken
Three different behaviours:
- Bracketed placeholder, dash still appended — frames 2, 3, 4, 5, 6, 8, 11.
"[no schematic loaded] — Schematic Editor". - Frame name alone, no dash and no placeholder — frames 9 and 10. GerbView
runs
SetTitle( _( "Gerber Viewer" ) )as a single string atgerbview_frame.cpp:667; the Image Converter builds the" — "insideif( !m_srcFileName.IsEmpty() )at:357-360, so an empty converter reads justImage Converter. - No empty branch at all — frames 1 and 7 always have a file name, empty or
not, and lean on
[Unsaved]to say so.
Ours prints Gerber Viewer - Gerber Viewer because the call site passes the
frame name as the placeholder and then appends the frame name again. Upstream
has no placeholder here to pass.
C. The suffixes are not one set
[Read Only]— frames 1, 2, 4, 7, 11.[Read Only Library]— frame 3 only. A different string, on a library rather than a file (symbol_editor.cpp:78-79).[Unsaved]— frames 1, 2, 4, 7.[from schematic]— frame 3 only, on a symbol opened from a schematic (symbol_editor.cpp:66).[from <project>.kicad_pcb]— frame 4 only, on a footprint opened from the board rather than a library. The project name and the extension are interpolated:wxString::Format( _( "[from %s]" ), Prj().GetProjectName() + "." + FILEEXT::PcbFileExtension )(footprint_edit_frame.cpp:1092-1094). In that branch the document part is the footprint's reference, not its FPID.[<sheetPath>]— frame 2 only, and only when the human-readable sheet path differs from the file name (sch_edit_frame.cpp:1844-1847).
The predicates differ too, and are worth copying rather than guessing:
- PCB (
:2174-2178):readOnly = !fn.IsFileWritable()whenfn.IsOk() && fn.FileExists(), elseunsaved = true. The two are mutually exclusive. - Schematic (
:1824-1829): same shape, butreadOnly = screen->IsReadOnly()and the existence test isscreen->FileExists(). - Simulator (
:317-328): same shape again, over the workbook file. - Footprint editor (
:1100-1122): not mutually exclusive by file state —[Read Only]on a saved footprint whose library is not writable,[Unsaved]on a footprint whose library item name is empty. Two different branches. - Manager (
:1300-1301):Prj().IsReadOnly(), and no unsaved case.
D. The footprint editor has four branches, not two
Worth spelling out because it is the most-branched of the thirteen
(footprint_edit_frame.cpp:1080-1132):
- footprint came from the board →
*+reference+[from <project>.kicad_pcb] - footprint came from a library →
*+FPID.Format()+[Read Only]if the library is not writable - footprint has a library item name but no valid FPID →
*+FPID.GetLibItemName()+[Unsaved], unconditionally - nothing loaded →
[no footprint loaded]
E. Where the * goes
Always first, always with no space after it: wxT( "*" ) then += name. Frames
1, 2, 3, 4, 8. The simulator writes it as wxT( "*" ) + filename.GetName() in
one expression (:330) but the result is identical.
F. Two frames are not this pattern at all
pcb_calculator_frame.cpp:240 sets a fixed _( "Calculator Tools" ) with no
document and no dash. The 3D viewer child frame builds
_( "3D Viewer" ) + " — " + <footprint name> — the frame name comes first
there, which is the reverse of every other frame — and its standalone form is a
bare _( "3D Viewer" ) (eda_3d_viewer_frame.cpp:634).
What ours does today
FRAME_TITLE_SEPARATOR (—) and frameTitleName() exist in
designer/src/ui/useDocumentTitle.ts and two call sites use them, both in
the drawing sheet editor. Six launchers hand-roll an ASCII hyphen instead:
editors/pcb/PcbEditor.tsx:7515 - PCB Editor
editors/pcb/PcbEditor.tsx:8302 - 3D Viewer
editors/gerbview/GerberViewer.tsx:925 - Gerber Viewer
editors/schematic/SchematicEditor.tsx:7214 - Schematic Editor
editors/symbol/SymbolEditor.tsx:1696 - Symbol Editor
editors/footprint/FootprintEditor.tsx:1136 - Footprint Editor
None of the six renders *, [Read Only] or [Unsaved], and the PCB editor's
document part strips .kicad_pcb with a regex of its own
(PcbEditor.tsx:7513) rather than through frameTitleName.
Gerber Viewer additionally uses projectName as its document part, which is the
wrong value entirely: GerbView's title is the active layer's gerber file
name (gerbview_frame.cpp:661, 684), and has nothing to do with a project.