
== Advanced topics

=== Configuration and Customization

Pcbnew has a variety of preferences that can be configured through the Preferences dialog. Like
all parts of KiCad, the preferences for Pcbnew are stored in the user configuration directory, and
are independent between KiCad minor versions to allow multiple versions to run side-by-side with
independent preferences.

The first sections of the Preferences dialog (Common, Mouse and Touchpad, and Hotkeys) are shared
between all KiCad programs. These sections are described in detail in the KiCad manual under the
"Common preferences" section. Note that even though the Hotkeys section is shared between all
programs, there are many Pcbnew-specific hotkeys that only appear in the list when Pcbnew is
running.

==== Display options

image::images/pcbnew_preferences_display.png[scaledwidth="50%"]

**Grid style:** Controls how the alignment grid is drawn.

**Grid thickness:** Controls how thick grid lines or dots are drawn.

**Min grid spacing:** Controls the minimum distance, in pixels, between two grid lines. Grid line
that violate this minimum spacing will not be drawn, regardless of the current grid setting.

**Snap to grid:** Controls when drawing and editing operations will be snapped to coordinates on
the active grid.  "Always" will enable snapping even when the grid is hidden; "When grid shown"
will enable snapping only when the grid is visible.

NOTE: Grid snapping can be temporarily disabled by holding down `Shift`.

**Cursor shape:** Controls whether the editing cursor is drawn as a small crosshair or a
full-screen crosshair (a set of lines covering the entire drawing canvas).  The editing cursor
shows where the next drawing or editing action will occur, and will be snapped to a grid location
if snapping is enabled.

**Always show crosshairs:** Controls whether the editing cursor is shown all the time, or only
when an editing or drawing tool is active.

**Net names:** Controls whether or not net name labels are drawn on copper objects. These labels
are guides for editing only, and do not appear in fabrication outputs.

**Show pad numbers:** Controls whether or not pad number labels are drawn on footprint pads.

**Show pad <no net> indicator:** Controls whether or not pads with no net are indicated with a
special marker.

**Track clearance:** Controls whether or not clearance outlines around tracks and vias are shown.
Clearance outlines are shown as thin shapes around objects that indicate the minimum clearance to
other objects, as defined by constraints and design rules.

**Show pad clearance:** Controls whether or not clearance outlines around pads are shown.

**Center view on cross-probed items:** When both Eeschema and Pcbnew are running, controls whether
clicking a component or pin in Eeschema will center the Pcbnew view on the corresponding footprint
or pad.

**Zoom to fit cross-probed items:** Controls whether the view will be zoomed to show a
cross-probed footprint or pad.

**Highlight cross-probed nets:** Controls whether or not nets highlighted in Eeschema will be
highlighted in Pcbnew when the highlight tool is activated in both tools.

==== Editing options

image::images/pcbnew_preferences_editing.png[scaledwidth="50%"]

**Lock pads of newly added footprints:** Controls whether or not the pads of footprints will
default to locked or unlocked (editable).

**Flip board items L/R:** Controls the direction board items will be flipped when moving them
between the top and bottom layers.

**Limit graphic lines to H, V and 45 degrees:** Controls whether lines drawn with the graphic
drawing tools can take on any angle. Note that this only affects drawing new lines: lines can be
edited to take on any angle.

**Magnetic points:** This section controls object snapping, also called magnetic points.  Object
snapping takes precedence over grid snapping when it is enabled.  Object snapping only works to
objects on the active layer. Hold `Alt` to temporary disable object snapping.

**Snap to pads:** Controls when the editing cursor will snap to pad origins.

**Snap to tracks:** Controls when the editing cursor will snap to track segment endpoints.

**Snap to graphics:** Controls when the editing cursor will snap to graphic shape points.

**Always show selected ratsnest:** When enabled, the ratsnest for a selected footprint will always
be shown even if the global ratsnest is hidden.

**Show ratsnest with curved lines:** Controls whether ratsnest lines are drawn straight or curved.

**Show page limits:** Controls whether or not the page boundary is drawn as a rectangle.

**Mouse drag track behavior:** Controls the action that will occur when you drag a track segment
with the mouse: "Move" will move the track segment independent of any others. "Drag" will invoke
the push-and-shove router to drag the track, respecting design rules and keeping other track
segments attached.

==== Colors

image::images/pcbnew_preferences_colors.png[scaledwidth="50%"]

Pcbnew supports switching between different color themes to match your preferences. Kicad 6.0
comes with two built-in color themes: "KiCad Default" is a new theme designed to have good
contrast and balance for most cases, and is the default for new installations. "KiCad Classic" is
the default theme from KiCad 5.1 and earlier versions. Both of these built-in themes cannot be
modified, but you can create new themes to customize the look of Pcbnew as well as install themes
made by other users.

Color themes are stored in JSON files located in the `colors` subdirectory of the KiCad
configuration directory.  The "Open Theme Folder" button will open this location in your system
file manager, making it easy to manage your installed themes. To install a new theme, place it in
this folder and restart KiCad. The new theme will be available from the drop-down list of color
themes if the file is a valid color theme file.

To create a new color theme, choose New Theme... from the drop-down list of color themes.  Enter a
name for your theme, and then begin editing colors.  The colors in the new theme will be copied
from whatever theme was selected before you created the new theme.

To change a color, double-click or middle-click the color swatch in the list.  The "Reset to
Default" button will reset that color to its corresponding entry in the "KiCad Default" color
theme.

Color themes are saved automatically; all changes are reflected immediately when you close the
Preferences dialog.  The window on the right side of the dialog shows a preview of how the
selected theme will look.

==== Action plugins

NOTE: TODO: Write this section

==== Origin & axes

image::images/pcbnew_preferences_origin_axes.png[scaledwidth="50%"]

**Display origin:** Determines which coordinate origin is used for coordinate display in the editing canvas. The page origin is fixed at the corner of the page. The drill/place file origin and the grid origin can be moved by the user.

**X axis:** Controls whether X-coordinates increase to the right or to the left.

**Y axis:** Controls whether Y-coordinates increase upwards or downwards.

=== Custom design rules

The custom design rule language is based on s-expressions and allows you to create design
constraints that are not possible with the built-in constraints.  Each design rule generally
contains an expression defining what objects to match, adn a constraint defining the rule to be
applied to the matched objects.

==== Custom rule syntax

NOTE: TODO: Write this section

==== Custom design rule examples

NOTE: TODO: Write this section

=== Scripting

Scripting allows you to automate tasks within KiCad using the https://www.python.org/[Python]
language. It is possible to add functionality to Pcbnew through Python "action plugins" that can
be added to the top toolbar. It is also possible to write standalone scripts that interact with
KiCad files, for example, to generate fabrication outputs from a board file automatically.

This manual covers general scripting concepts. Users wishing to write or modify scripts should
also use the Doxygen documentation located at
https://docs.kicad.org/doxygen-python/namespaces.html[https://docs.kicad.org/doxygen-python/namespaces.html].

KiCad can be built with support for Python 2 or Python 3. Release builds of KiCad 6 and later will
generally be built with Python 3 support, as Python 2 is no longer maintained.

==== Python script locations

NOTE: TODO: fill this out with final 6.0 scripting locations for each platform

==== Action plugins

NOTE: TODO: Write this section (how to install new action plugins)

==== Footprint wizards

The footprint wizards are a collection of python scripts that can be accessed from the Footprint
Editor. If you invoke the footprint dialog you select a given wizard that allows you to see the
footprint rendered, and you have some parameters you can edit.

If the plugins are not properly distributed to your system package, you can find the latest
versions in the KiCad source tree at
link:https://gitlab.com/kicad/code/kicad/tree/master/pcbnew/python/plugins[gitlab].

==== Using the scripting console

Pcbnew comes with a built-in Python console that can be used to inspect and interact with the
board.  To launch the console, use the image:images/icons/py_script.png[] icon in the top toolbar.
The Pcbnew Python API is not automatically loaded, so to load it, type `import pcbnew` into the
console. The command `pcbnew.GetBoard()` will then return a reference to the board currently
loaded in Pcbnew, which can be inspected and modified through the console.

NOTE: TODO: Document the other useful PyAlaMode functions

==== Writing external scripts

NOTE: TODO: Write this section

==== Writing action plugins

NOTE: TODO: Write this section

