================
Symbol Libraries
================

Where symbols come from
=======================

While you draw, symbols are taken from the application's **system library**
(the shipped set listed in :doc:`/GUI/schematics/placing_symbols`).  Each symbol is an SVG
``<g>`` element that carries its own metadata in ``data-*`` attributes:

.. code-block:: xml

   <g id="R"
      data-prefix="R"
      data-nodes="pos neg"
      data-model="R"
      data-params="value dcvar dcvarlot noisetemp noiseflow"
      data-description="Resistor (nonzero resistance)"
      data-info="https://www.slicap.org/syntax/devices.html#r-resistor">
      ...artwork and pin markers...
   </g>

The editor reads everything it needs from these attributes — there is no
separate table to keep in sync.

* ``data-prefix`` — the device letter / reference-designator prefix.
* ``data-nodes`` — the node names, in the order the netlister expects.  A pin's
  position is given by a ``<circle class="node" data-node="...">`` marker.
* ``data-model`` — the SLiCAP model name.
* ``data-params`` — the parameters the user may set.
* ``data-description`` / ``data-info`` — the text and link shown in the
  Properties dialog.

The symbol's outline extent (used for selection) is computed from its geometry,
so symbols never need a hand-maintained bounding box.

Frozen copies travel with the schematic
=======================================

When you **save**, the symbols the schematic uses are copied into its
``<name>.symbols`` sidecar (see :doc:`/GUI/project/project`).  When you **open** a
schematic, those frozen copies are loaded *on top of* the system library, so the
drawing always renders with the symbols it was created with — even if the
shipped symbols change later.

Symbol library files
====================

A symbol library file is plain SVG whose extension names the dialect,
in the same way as schematics (``.slicap_sch`` / ``.spice_sch``) and
subcircuit libraries (``.slicap_lib`` / ``.spice_lib``):

* ``<name>.slicap_sym`` — symbols for SLiCAP schematics
* ``<name>.spice_sym`` — symbols for NGspice schematics

The shipped libraries are ``Symbols.slicap_sym``, ``Symbols-extended.slicap_sym``
and ``Symbols.spice_sym`` in the package.  A project's own symbols live in its
``lib/`` folder, one file per symbol, next to the subcircuit packages: the
block symbols generated by *New subcircuit symbol* and the symbols imported
with *Tools → Import symbols from file*.  The library loader offers every
``.slicap_sym`` of ``lib/`` on the project's SLiCAP schematics and every
``.spice_sym`` on its NGspice schematics.  A plain ``.svg`` in ``lib/`` carries
no dialect and is offered on both, with a warning in the terminal.  Files
saved by earlier versions as ``<name>_slicap_symbol.svg`` or
``<name>_spice_symbol.svg`` are still read and are renamed to the new form
when a schematic of the project is opened.

Custom symbols
==============

Draw the symbol in any SVG editor and give the ``<g>`` element the metadata
shown above.  A minimal template for a four-pin device on an NGspice
schematic, a transistor package with two emitter pins that a subcircuit
``QPKG`` joins internally:

.. code-block:: xml

   <svg xmlns="http://www.w3.org/2000/svg">
     <g id="QPKG"
        data-prefix="X"
        data-nodes="c b e1 e2"
        data-model="QPKG|1"
        data-params=""
        data-description="Transistor package, two emitter pins">
       <rect x="-20" y="-20" width="40" height="40" fill="none" stroke="black"/>
       <circle cx="0"   cy="-20" r="0.5" class="node" data-node="c"/>
       <circle cx="-20" cy="0"   r="0.5" class="node" data-node="b"/>
       <circle cx="-5"  cy="20"  r="0.5" class="node" data-node="e1"/>
       <circle cx="5"   cy="20"  r="0.5" class="node" data-node="e2"/>
     </g>
   </svg>

Coordinates are scene units with the origin at the symbol's centre; pins sit
on grid points.  ``data-model`` is ``name|show``: the model name and whether
it is shown on the canvas.  One file may hold several symbols.  Then use
:menuselection:`Tools --> Import symbols from file…` on a schematic of the
intended type: the dialog lists every symbol of the file with its prefix and
pin count, reports the ones that do not parse and why, and writes the ticked
ones into ``lib/`` under the schematic's dialect extension.  A symbol whose
name equals a system symbol's overrides it in the palette; the dialog says
so.

Overriding symbols
==================

Because a frozen symbol overrides the system symbol of the same name, you can
customise how a device looks.  For example, you can draw the nullor ``N`` as an
operational-amplifier triangle, freeze it into a schematic's ``.symbols``, and
that schematic will use your version while everything else keeps the standard
IEC symbol.

.. todo::

   A graphical in-app symbol editor, with a defined origin and grid, is
   planned.  Until then, custom symbols are authored in an SVG editor and
   imported as described above.
