HiNC-2025-win-desktop-Deploy/App/wwwroot/HiAPI-docsite/anatomy/execution/mission/NcFileCommand-panel.html

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
      <title>NcFileCommand Panel (Program File) | HiAPI-C# 2025 </title>
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <meta name="title" content="NcFileCommand Panel (Program File) | HiAPI-C# 2025 ">
      
      
      <link rel="icon" href="../../../img/HiAPI.favicon.ico">
      <link rel="stylesheet" href="../../../public/docfx.min.css">
      <link rel="stylesheet" href="../../../public/main.css">
      <meta name="docfx:navrel" content="../../../toc.html">
      <meta name="docfx:tocrel" content="toc.html">
      
      <meta name="docfx:rel" content="../../../">
      
      
      
      <meta name="loc:inThisArticle" content="In this article">
      <meta name="loc:searchResultsCount" content="{count} results for &quot;{query}&quot;">
      <meta name="loc:searchNoResults" content="No results for &quot;{query}&quot;">
      <meta name="loc:tocFilter" content="Filter by title">
      <meta name="loc:nextArticle" content="Next">
      <meta name="loc:prevArticle" content="Previous">
      <meta name="loc:themeLight" content="Light">
      <meta name="loc:themeDark" content="Dark">
      <meta name="loc:themeAuto" content="Auto">
      <meta name="loc:changeTheme" content="Change theme">
      <meta name="loc:copy" content="Copy">
      <meta name="loc:downloadPdf" content="Download PDF">

      <script type="module" src="./../../../public/docfx.min.js"></script>

      <script>
        const theme = localStorage.getItem('theme') || 'auto'
        document.documentElement.setAttribute('data-bs-theme', theme === 'auto' ? (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light') : theme)
      </script>

  </head>

  <body class="tex2jax_ignore" data-layout="" data-yaml-mime="">
    <header class="bg-body border-bottom">
      <nav id="autocollapse" class="navbar navbar-expand-md" role="navigation">
        <div class="container-xxl flex-nowrap">
          <a class="navbar-brand" href="../../../index.html">
            <img id="logo" class="svg" src="../../../img/HiAPI.logo.png" alt="">
            
          </a>
          <button class="btn btn-lg d-md-none border-0" type="button" data-bs-toggle="collapse" data-bs-target="#navpanel" aria-controls="navpanel" aria-expanded="false" aria-label="Toggle navigation">
            <i class="bi bi-three-dots"></i>
          </button>
          <div class="collapse navbar-collapse" id="navpanel">
            <div id="navbar">
              <form class="search" role="search" id="search">
                <i class="bi bi-search"></i>
                <input class="form-control" id="search-query" type="search" disabled placeholder="Search" autocomplete="off" aria-label="Search">
              </form>
            </div>
          </div>
        </div>
      </nav>
    </header>

    <main class="container-xxl">
      <div class="toc-offcanvas">
        <div class="offcanvas-md offcanvas-start" tabindex="-1" id="tocOffcanvas" aria-labelledby="tocOffcanvasLabel">
          <div class="offcanvas-header">
            <h5 class="offcanvas-title" id="tocOffcanvasLabel">Table of Contents</h5>
            <button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#tocOffcanvas" aria-label="Close"></button>
          </div>
          <div class="offcanvas-body">
            <nav class="toc" id="toc"></nav>
          </div>
        </div>
      </div>

      <div class="content">
        <div class="actionbar">
          <button class="btn btn-lg border-0 d-md-none" type="button" data-bs-toggle="offcanvas" data-bs-target="#tocOffcanvas" aria-controls="tocOffcanvas" aria-expanded="false" aria-label="Show table of contents">
            <i class="bi bi-list"></i>
          </button>

          <nav id="breadcrumb"></nav>
        </div>

        <article data-uid="Anatomy-NcFileCommandPanel">
          <h1 id="ncfilecommand-panel-program-file">NcFileCommand Panel (Program File)</h1>

<p>The key model is <a class="xref" href="../../../api/Hi.SessionCommands.NcFileCommand.html">NcFileCommand</a>.</p>
<p>The command carries exactly two values: <a class="xref" href="../../../api/Hi.SessionCommands.NcFileCommand.html#Hi_SessionCommands_NcFileCommand_NcFile">NcFile</a>, the path of
the program to play, and <a class="xref" href="../../../api/Hi.SessionCommands.NcFileCommand.html#Hi_SessionCommands_NcFileCommand_NcKind">NcKind</a>, the runner that plays it.
The program text stays a file on disk — the project stores the path and nothing else, which is what
separates this command from <a class="xref" href="NcCodeCommand-panel.html">NC Code</a>, whose text is serialized
into the project itself.</p>
<p><code>NcFile</code> is normally a path relative to the project folder — that is what the browse dialog yields —
and an absolute path on the server is accepted just as well. No base directory is stored with the
command: at play time <a class="xref" href="../../../api/Hi.MachiningProcs.SessionShell.html#Hi_MachiningProcs_SessionShell_RunNcFile_">RunNcFile</a> hands the stored path
together with the project's own base directory to the local project service, and that is where a
relative path acquires its root; the convention behind it is the
<a class="xref" href="../../conventions/gui-file-path-assignment.html">Load Pattern</a>.</p>
<p>The panel renders on the command's own node under the Mission root of the Execution page's Control
Tree. The editor pane holds the editor and, while the command's tree checkbox is off, a one-line
disabled hint above it — nothing structural: the command's move up / move down / duplicate / delete
buttons and its drag handle sit on its tree row, and the Add Command <code>+</code> sits on the row of the
list that holds it. This command has no editable Title field — unlike NC Code, Script and List —
so its tree row label is composed from the path alone: <code>Program File [path]</code>, the path being the
detail the label brackets.</p>
<div class="NOTE">
<h5>Note</h5>
<p>The GUI labels this command &ldquo;Program File&rdquo;: it plays NC, CL (CLSF) and CSV files — the runner is
picked by <a class="xref" href="../../../api/Hi.SessionCommands.NcFileCommand.html#Hi_SessionCommands_NcFileCommand_NcKind">NcKind</a>, and
<a class="xref" href="../../../api/Hi.MachiningProcs.NcKind.html#Hi_MachiningProcs_NcKind_Auto">Auto</a> reads it off the extension
(<a class="xref" href="../../../api/Hi.MachiningProcs.NcKindUtil.html#Hi_MachiningProcs_NcKindUtil_DetectByPath_">DetectByPath</a>: <code>.cl</code>, <code>.cls</code> and <code>.clsf</code> play as CL, <code>.csv</code>
as CSV, and every other extension as brand NC).</p>
</div>
<h2 id="layout">Layout</h2>
<ul>
<li>NcFileCommand Panel
<ul>
<li>Head Line
<ul>
<li>Program File Path Field
<ul>
<li>The model is <a class="xref" href="../../../api/Hi.SessionCommands.NcFileCommand.html#Hi_SessionCommands_NcFileCommand_NcFile">NcFile</a>.</li>
<li>Its hint names both accepted forms: an absolute path on the server, or a path relative to
the project folder.</li>
<li>Every keystroke saves the path. Leaving the field or pressing Enter additionally refreshes
the file-info banner.</li>
<li>The field flexes to fill the row beside the Browse button at any panel width.</li>
</ul>
</li>
<li>Browse Button
<ul>
<li>Opens the shared file-explorer dialog — see <a href="#browsing-for-a-program">Browsing for a Program</a>.</li>
</ul>
</li>
</ul>
</li>
<li>Play As Select
<ul>
<li>The model is <a class="xref" href="../../../api/Hi.SessionCommands.NcFileCommand.html#Hi_SessionCommands_NcFileCommand_NcKind">NcKind</a>.</li>
<li>Four choices: Auto (by extension), Brand NC, CL (CLSF) and CSV. The hint restates what Auto
detects, so the runner can be pinned when the extension would route the file elsewhere.</li>
</ul>
</li>
<li>File Info Banner
<ul>
<li>Appears once the path field is non-empty. Every fact in it is read on the server.</li>
<li>Found: a green banner stating the file size, its modified stamp and its line count, with a
Preview button in the banner's action slot.</li>
<li>Missing: an orange banner saying the file is not found on the server, and no Preview button.</li>
</ul>
</li>
<li>Preview Dialog
<ul>
<li>Read-only. The server returns the file's first 100 lines and the dialog shows them in a
monospace block that scrolls within 60% of the viewport height, inside a card capped at 80%.
An empty file previews as &quot;(empty)&quot;.</li>
</ul>
</li>
</ul>
</li>
</ul>
<h2 id="browsing-for-a-program">Browsing for a Program</h2>
<p>Browse opens the shared server-side file explorer dialog. File reads happen on the server; the
browser never uploads file bytes.</p>
<p>The <a class="xref" href="../../conventions/gui-file-path-assignment.html">Load Pattern</a>'s general web convention offers the Admin,
Project and Resource roots. This picker narrows to one: it opens on the project directory and allows
no other root, so a pick always yields a project-relative path. A file outside the project is
reached by typing its absolute path into the path field, which the server accepts.</p>
<p>The dialog carries four filter groups rather than one catch-all:</p>
<ul>
<li><strong>NC Files</strong> — <code>.nc</code>, <code>.anc</code>, <code>.tap</code>, <code>.eia</code>, <code>.mpf</code>, <code>.spf</code>, <code>.cnc</code>, <code>.ptp</code>, <code>.h</code>. The open set:
brand controller extensions, of which these are the common ones rather than all of them.</li>
<li><strong>CL Files</strong> — <code>.cl</code>, <code>.cls</code>, <code>.clsf</code>.</li>
<li><strong>CSV Files</strong> — <code>.csv</code>.</li>
<li><strong>All Files</strong> — an empty extension list, which is the empty filter the Load Pattern asks every
browser to preserve. It is the backstop for a brand extension the NC group does not name.</li>
</ul>
<p>CL and CSV are split out because they are closed extension sets: those are exactly the extensions
Auto routes to the CL and CSV runners, and everything else falls through to brand NC.</p>
<h2 id="multi-pick-fan-out">Multi-Pick Fan-Out</h2>
<p>The dialog is multi-select, and this is the one command editor that grows the mission. The first
picked file lands on this command. Each further pick becomes a <strong>new</strong> Program File command,
inserted into the list this command sits in at the index directly after it, in pick order — one
insert per pick, each at the next index, and the same list, so a command inside a nested list fans
out inside that nested list. The panel then reports the insert range — the first new index and
the count — and the command's slave panel scopes it to the owning list and names this command as
the selection. The Control Tree host takes that insert on its structure-changed path, which shares
two things with its own row ops — it holds the busy gate for the rebuild (a change arriving while
another op is in flight is not rebuilt) and carries the index-based ids (the expansion set and the
Add focus) over the new siblings — and not the third: the open panel's dirty gate, which every
row op runs first, is not part of this path. It then rebuilds the owning list's branch around the
new rows and leaves the selection on this command, whose own index is unchanged.</p>
<h2 id="where-the-program-text-is-edited">Where the Program Text Is Edited</h2>
<p>The command stores a path, and the panel does not edit the file. It assigns the path, picks the
runner, reports what the server knows about the file, and previews its first 100 lines read-only.
Nothing in the browser writes NC bytes back; the two file endpoints this panel calls are both reads.</p>
<h2 id="source-code-path">Source Code Path</h2>
<p>See <a class="xref" href="../../index.html">HiNC App Anatomy</a> for git repository links.</p>
<h3 id="web-application">Web Application</h3>
<p>HiNC-2025-webservice (Quasar CLI SPA):</p>
<ul>
<li><code>wwwroot-src/src/components/mission/NcFileCommandPanel.vue</code> — this panel: the path field and
Browse, the &ldquo;Play As&rdquo; kind select, the file-info banner and its Preview button, the read-only
preview dialog, the four filter groups, and the multi-pick fan-out.</li>
<li><code>wwwroot-src/src/components/widgets/FileExplorerDialog.vue</code> — the shared server-side browser
Browse opens: the pickable / multi / filters / initial-root / allowed-roots props, and the pick
event whose emitted strings pair a root name with a relative path — that relative half is what the
command stores.</li>
<li><code>wwwroot-src/src/components/widgets/fileFilter.ts</code> — the filter shape the four groups are built
from; an empty extension list means all files.</li>
<li><code>wwwroot-src/src/components/controlTree/missionItemTypes.ts</code> — maps the <code>ncfile</code> kind to this
panel. A kind absent from that map is served by the generic field editor instead.</li>
<li><code>wwwroot-src/src/components/controlTree/MissionCommandSlavePanel.vue</code> — the command node's
slave panel: mounts this editor on the entry path, and re-scopes the fan-out's structure change
to the owning list, with the insert range and this command as the selection.</li>
<li><code>wwwroot-src/src/components/controlTree/ControlTreePanel.vue</code> — the tree rows: the drag handle
and the move / duplicate / delete buttons on the command's row, and the Add Command <code>+</code> on the
row of its list.</li>
<li><code>wwwroot-src/src/components/controlTree/useControlTreeHost.ts</code> — takes the fan-out's insert on
its structure-changed path: the busy gate held for the rebuild, the index-based ids carried over
the new siblings (the two guarantees shared with the row ops; the dirty gate is not one of them),
the rebuild scoped to the owning list, and the selection the payload names.</li>
<li><code>wwwroot-src/src/api/mission.ts</code> — <code>loadNcFile</code>, <code>setNcFilePath</code>, <code>setNcFileNcKind</code>,
<code>getNcFileInfo</code> and <code>previewNcFile</code>, plus the kind union and the file-info shape; <code>addEntry</code>,
which the fan-out calls with the insert index and which answers the new entry's path.</li>
<li><code>wwwroot-src/src/i18n/en/mission.ts</code> — the panel's wording: the path hint, the Play As hint, the
four filter labels, the banner's found and not-found lines, and the preview titles.</li>
<li><code>Missions/MissionController.cs</code> — four endpoints serve this command: a PUT for the path, a PUT for
the NC kind, and the two server-side reads behind the banner and the preview (both POSTs, both
resolving a relative path against the project folder). The fan-out's extra picks go through the
list-entry POST, which lands the new entry at the requested insert index — clamped to the list,
the tail when none is given — and answers its index and dotted path. The command-snapshot builder
emits the file path and the NC kind for this kind of command.</li>
</ul>
<h3 id="hiapi-engine">HiAPI Engine</h3>
<ul>
<li><code>HiNc/SessionCommands/NcFileCommand.cs</code> — the model: <code>NcFile</code>, <code>NcKind</code> defaulting to Auto, the
&ldquo;Program File&rdquo; display name and its Program-category catalog registration, the XML round-trip that
writes the path verbatim, the <code>Program File [path]</code> row label, and <code>Run</code> handing path and kind to
the session shell.</li>
<li><code>HiMech/MachiningProcs/NcKind.cs</code> — the kind enum (Auto / BrandNc / Cl / Csv) and the
detect-by-path helper, the authority for what Auto does.</li>
<li><code>HiNc/MachiningProcs/SessionShell.cs</code> — <code>RunNcFile</code> passes the stored path together with the
project's base directory to the local project service.</li>
</ul>
<h2 id="see-also">See Also</h2>
<ul>
<li><a class="xref" href="NcCodeCommand-panel.html">NcCodeCommand Panel</a> — the other Program command: NC text stored in the project instead of a path to a file</li>
<li><a href="../../../manual/run/playing-a-program.html">Playing a Program</a> — the task these two commands serve</li>
<li><a href="index.html">Mission</a> — the rest of the command panels</li>
</ul>

</article>

        <div class="contribution d-print-none">
        </div>

        <div class="next-article d-print-none border-top" id="nextArticle"></div>

      </div>

      <div class="affix">
        <nav id="affix"></nav>
      </div>
    </main>

    <div class="container-xxl search-results" id="search-results"></div>

    <footer class="border-top text-secondary">
      <div class="container-xxl">
        <div class="flex-fill">
          <span> Copyright © 2025 <a href='https://superhightech.com.tw'>Tech Coordinate</a>. All rights reserved. <a href='https://superhightech.com.tw'>超級高科技股份有限公司</a> © 2025 版權所有 </span>
        </div>
      </div>
    </footer>
  </body>
</html>