@c key actions
@c ./../src/action.c 225

Many actions take a @code{delta} parameter as the last parameter,
which is an amount to change something.  That @code{delta} may include
units, as an additional parameter, such as @code{Action(Object,5,mm)}.
If no units are specified, the default is PCB's native units
(currently 1/100 mil).  Also, if the delta is prefixed by @code{+} or
@code{-}, the size is increased or decreased by that amount.
Otherwise, the size size is set to the given amount.

@example
Action(Object,5,mil)
Action(Object,+0.5,mm)
Action(Object,-1)
@end example

Actions which take a @code{delta} parameter which do not accept all
these options will specify what they do take.

@c ./../src/action.c 229

@macro pinshapes

Pins, pads, and vias can have various shapes.  All may be round.  Pins
and pads may be square (obviously "square" pads are usually
rectangular).  Pins and vias may be octagonal.  When you change a
shape flag of an element, you actually change all of its pins and
pads.

Note that the square flag takes precedence over the octagon flag,
thus, if both the square and octagon flags are set, the object is
square.  When the square flag is cleared, the pins and pads will be
either round or, if the octagon flag is set, octagonal.

@end macro

@c ./../src/command.c 64

@macro colonaction

This is one of the command box helper actions.  While it is a regular
action and can be used like any other action, its name and syntax are
optimized for use with the command box (@code{:}) and thus the syntax
is documented for that purpose.

@end macro

@c ./../src/action.c 227

Many actions act on indicated objects on the board.  They will have
parameters like @code{ToggleObject} or @code{SelectedVias} to indicate
what group of objects they act on.  Unless otherwise specified, these
parameters are defined as follows:

@table @code

@item Object
@itemx ToggleObject
Affects the object under the mouse pointer.  If this action is invoked
from a menu or script, the user will be prompted to click on an
object, which is then the object affected.

@item Selected
@itemx SelectedObjects

Affects all objects which are currently selected.  At least, all
selected objects for which the given action makes sense.

@item SelectedPins
@itemx SelectedVias
@itemx Selected@var{Type}
@itemx @i{etc}
Affects all objects which are both selected and of the @var{Type} specified.

@end table


@menu
* core actions::
* common actions::
* gtk actions::
* lesstif actions::
@end menu

@node core actions
@section Core actions
@menu
* AddRats Action:: Add one or more rat lines to the board.
* ApplyVendor Action:: Applies the currently loaded vendor drill table to the current design.
* Atomic Action:: Save or restore the undo serial number.
* Attributes Action:: Let the user edit the attributes of the layout, current or given
layer, or selected element.
* AutoPlaceSelected Action:: Auto-place selected components.
* AutoRoute Action:: Auto-route some or all rat lines.
* ChangeClearSize Action:: Changes the clearance size of objects.
* ChangeDrillSize Action:: Changes the drilling hole size of objects.
* ChangeFlag Action:: Sets or clears flags on objects.
* ChangeHole Action:: Changes the hole flag of objects.
* ChangeJoin Action:: Changes the join (clearance through polygons) of objects.
* ChangeName Action:: Sets the name of objects.
* ChangeOctagon Action:: Changes the octagon-flag of pins and vias.
* ChangePaste Action:: Changes the no paste flag of objects.
* ChangePinName Action:: Sets the name of a specific pin on a specific element.
* ChangeSize Action:: Changes the size of objects.
* ChangeSquare Action:: Changes the square flag of pins and pads.
* ClearOctagon Action:: Clears the octagon-flag of pins and vias.
* ClearSquare Action:: Clears the square-flag of pins and pads.
* ClrFlag Action:: Clears flags on objects.
* Connection Action:: Searches connections of the object at the cursor position.
* Delete Action:: Delete stuff.
* DeleteRats Action:: Delete rat lines.
* DisableVendor Action:: Disables automatic drill size mapping.
* DisperseElements Action:: Disperses elements.
* Display Action:: Several display-related actions.
* djopt Action:: Perform various optimizations on the current board.
* DRC Action:: Invoke the DRC check.
* DumpLibrary Action:: Display the entire contents of the libraries.
* elementlist Action:: Adds the given element if it doesn't already exist.
* elementsetattr Action:: Sets or clears an element-specific attribute.
* EnableVendor Action:: Enables automatic drill size mapping.
* execcommand Action:: Runs a command.
* ExecuteFile Action:: Run actions from the given file.
* Flip Action:: Flip an element to the opposite side of the board.
* FontEdit Action:: Convert the current font to a PCB for editing.
* FontSave Action:: Convert the current PCB back to a font.
* FreeRotateBuffer Action:: Rotates the current paste buffer contents by the specified angle.  The
angle is given in degrees.  If no angle is given, the user is prompted
for one.

* GlobalPuller Action:: Pull all traces tight.
* h Action:: Print a help message for commands.
* Import Action:: Import schematics.
* l Action:: Loads layout data.
* le Action:: Loads an element into the current buffer.
* LoadFootprint Action:: Loads a single footprint by name.
* LoadFrom Action:: Load layout data from a file.
* LoadVendorFrom Action:: Loads the specified vendor resource file.
* m Action:: Loads a layout into the current buffer.
* MarkCrosshair Action:: Set/Reset the Crosshair mark.
* Message Action:: Writes a message to the log window.
* MinClearGap Action:: Ensures that polygons are a minimum distance from objects.
* MinMaskGap Action:: Ensures the mask is a minimum distance from pins and pads.
* Mode Action:: Change or use the tool mode.
* MorphPolygon Action:: Converts dead polygon islands into separate polygons.
* MoveLayer Action:: Moves/Creates/Deletes Layers.
* MoveObject Action:: Moves the object under the crosshair.
* MoveToCurrentLayer Action:: Moves objects to the current layer.
* Netlist Action:: Perform various actions on netlists.
* New Action:: Starts a new layout.
* OptAutoOnly Action:: Toggles the optimize-only-autorouted flag.
* PasteBuffer Action:: Various operations on the paste buffer.
* Polygon Action:: Some polygon related stuff.
* Puller Action:: Pull an arc-line junction tight.
* q Action:: Quits the application after confirming.
* q! Action:: Quits the application without confirming.
* Quit Action:: Quits the application after confirming.
* Redo Action:: Redo recent``undo''operations.
* RemoveSelected Action:: Removes any selected objects.
* Renumber Action:: Renumber all elements.  The changes will be recorded to filename
for use in backannotating these changes to the schematic.
* Report Action:: Produce various report.
* ReportDialog Action:: Report on the object under the crosshair
* RipUp Action:: Ripup auto-routed tracks, or convert an element to parts.
* rn Action:: Reads netlist.
* RouteStyle Action:: Copies the indicated routing style into the current sizes.
* s Action:: Saves layout data.
* SaveSettings Action:: Saves settings.
* SaveTo Action:: Saves data to a file.
* Select Action:: Toggles or sets the selection.
* SetFlag Action:: Sets flags on objects.
* SetOctagon Action:: Sets the octagon-flag of objects.
* SetSame Action:: Sets current layer and sizes to match indicated item.
* SetSquare Action:: sets the square-flag of objects.
* SetThermal Action:: Set the thermal (on the current layer) of pins or vias to the given style.
Style = 0 means no thermal.
Style = 1 has diagonal fingers with sharp edges.
Style = 2 has horizontal and vertical fingers with sharp edges.
Style = 3 is a solid connection to the plane.Style = 4 has diagonal fingers with rounded edges.
Style = 5 has horizontal and vertical fingers with rounded edges.

* SetValue Action:: Change various board-wide values and sizes.
* ToggleHideName Action:: Toggles the visibility of element names.
* ToggleVendor Action:: Toggles the state of automatic drill size mapping.
* Undo Action:: Undo recent changes.
* UnloadVendor Action:: Unloads the current vendor drill mapping table.
* Unselect Action:: Unselects the object at the pointer location or the specified objects.
* w Action:: Saves layout data.
* wq Action:: Saves the layout data and quits.
@end menu
@node AddRats Action
@subsection AddRats
@c key AddRats in hid 
@cartouche
@format
AddRats(AllRats|SelectedRats|Close)@end format
@end cartouche

Add one or more rat lines to the board.
@c ./../src/action.c 3310

@table @code

@item AllRats
Create rat lines for all loaded nets that aren't already connected on
with copper.

@item SelectedRats
Similarly, but only add rat lines for nets connected to selected pins
and pads.

@item Close
Selects the shortest unselected rat on the board.

@end table


@node ApplyVendor Action
@subsection ApplyVendor
@c key ApplyVendor in hid 
@cartouche
@format
ApplyVendor()@end format
@end cartouche

Applies the currently loaded vendor drill table to the current design.
@c ./../src/vendor.c 112
@cindex vendor map 
@cindex vendor drill table
@findex ApplyVendor()

This will modify all of your drill holes to match the list of allowed
sizes for your vendor.

@node Atomic Action
@subsection Atomic
@c key Atomic in hid 
@cartouche
@format
Atomic(Save|Restore|Close|Block)@end format
@end cartouche

Save or restore the undo serial number.
@c ./../src/action.c 1720

This action allows making multiple-action bindings into an atomic
operation that will be undone by a single Undo command.  For example,
to optimize rat lines, you'd delete the rats and re-add them.  To
group these into a single undo, you'd want the deletions and the
additions to have the same undo serial number.  So, you @code{Save},
delete the rats, @code{Restore}, add the rats - using the same serial
number as the deletes, then @code{Block}, which checks to see if the
deletions or additions actually did anything.  If not, the serial
number is set to the saved number, as there's nothing to undo.  If
something did happen, the serial number is incremented so that these
actions are counted as a single undo step.

@table @code

@item Save
Saves the undo serial number.

@item Restore
Returns it to the last saved number.

@item Close
Sets it to 1 greater than the last save.

@item Block
Does a Restore if there was nothing to undo, else does a Close.

@end table


@node Attributes Action
@subsection Attributes
@c key Attributes in hid 
@cartouche
@format
Attributes(Layout|Layer|Element)
Attributes(Layer,layername)@end format
@end cartouche

Let the user edit the attributes of the layout, current or given
layer, or selected element.
@c ./../src/action.c 6761

This just pops up a dialog letting the user edit the attributes of the
pcb, an element, or a layer.


@node AutoPlaceSelected Action
@subsection AutoPlaceSelected
@c key AutoPlaceSelected in hid 
@cartouche
@format
AutoPlaceSelected()@end format
@end cartouche

Auto-place selected components.
@c ./../src/action.c 3450

Attempts to re-arrange the selected components such that the nets
connecting them are minimized.  Note that you cannot undo this.


@node AutoRoute Action
@subsection AutoRoute
@c key AutoRoute in hid 
@cartouche
@format
AutoRoute(AllRats|SelectedRats)@end format
@end cartouche

Auto-route some or all rat lines.
@c ./../src/action.c 3471

@table @code

@item AllRats
Attempt to autoroute all rats.

@item SelectedRats
Attempt to autoroute the selected rats.

@end table

Before autorouting, it's important to set up a few things.  First,
make sure any layers you aren't using are disabled, else the
autorouter may use them.  Next, make sure the current line and via
styles are set accordingly.  Last, make sure "new lines clear
polygons" is set, in case you eventually want to add a copper pour.

Autorouting takes a while.  During this time, the program may not be
responsive.


@node ChangeClearSize Action
@subsection ChangeClearSize
@c key ChangeClearSize in hid 
@cartouche
@format
ChangeClearSize(Object, delta)
ChangeClearSize(SelectedPins|SelectedPads|SelectedVias, delta)
ChangeClearSize(SelectedLines|SelectedArcs, delta
ChangeClearSize(Selected|SelectedObjects, delta)@end format
@end cartouche

Changes the clearance size of objects.
@c ./../src/action.c 3686

If the solder mask is currently showing, this action changes the
solder mask clearance.  If the mask is not showing, this action
changes the polygon clearance.


@node ChangeDrillSize Action
@subsection ChangeDrillSize
@c key ChangeDrillSize in hid 
@cartouche
@format
ChangeDrillSize(Object, delta)
ChangeDrillSize(SelectedPins|SelectedVias|Selected|SelectedObjects, delta)@end format
@end cartouche

Changes the drilling hole size of objects.
@c ./../src/action.c 3630


@node ChangeFlag Action
@subsection ChangeFlag
@c key ChangeFlag in hid 
@cartouche
@format
ChangeFlag(Object|Selected|SelectedObjects, flag, value)
ChangeFlag(SelectedLines|SelectedPins|SelectedVias, flag, value)
ChangeFlag(SelectedPads|SelectedTexts|SelectedNames, flag, value)
ChangeFlag(SelectedElements, flag, value)
flag = square | octagon | thermal | join
value = 0 | 1@end format
@end cartouche

Sets or clears flags on objects.
@c ./../src/action.c 5750

Toggles the given flag on the indicated object(s).  The flag may be
one of the flags listed above (square, octagon, thermal, join).  The
value may be the number 0 or 1.  If the value is 0, the flag is
cleared.  If the value is 1, the flag is set.


@node ChangeHole Action
@subsection ChangeHole
@c key ChangeHole in hid 
@cartouche
@format
ChangeHole(ToggleObject|Object|SelectedVias|Selected)@end format
@end cartouche

Changes the hole flag of objects.
@c ./../src/action.c 4571

The "hole flag" of a via determines whether the via is a
plated-through hole (not set), or an unplated hole (set).


@node ChangeJoin Action
@subsection ChangeJoin
@c key ChangeJoin in hid 
@cartouche
@format
ChangeJoin(ToggleObject|SelectedLines|SelectedArcs|Selected)@end format
@end cartouche

Changes the join (clearance through polygons) of objects.
@c ./../src/action.c 4199

The join flag determines whether a line or arc, drawn to intersect a
polygon, electrically connects to the polygon or not.  When joined,
the line/arc is simply drawn over the polygon, making an electrical
connection.  When not joined, a gap is drawn between the line and the
polygon, insulating them from each other.


@node ChangeName Action
@subsection ChangeName
@c key ChangeName in hid 
@cartouche
@format
ChangeName(Object)
ChangeName(Layout|Layer)@end format
@end cartouche

Sets the name of objects.
@c ./../src/action.c 4005

@table @code

@item Object
Changes the name of the element under the cursor.

@item Layout
Changes the name of the layout.  This is printed on the fab drawings.

@item Layer
Changes the name of the currently active layer.

@end table


@node ChangeOctagon Action
@subsection ChangeOctagon
@c key ChangeOctagon in hid 
@cartouche
@format
ChangeOctagon(Object|ToggleObject|SelectedObjects|Selected)
ChangeOctagon(SelectedElements|SelectedPins|SelectedVias)@end format
@end cartouche

Changes the octagon-flag of pins and vias.
@c ./../src/action.c 4403

@pinshapes


@node ChangePaste Action
@subsection ChangePaste
@c key ChangePaste in hid 
@cartouche
@format
ChangePaste(ToggleObject|Object|SelectedPads|Selected)@end format
@end cartouche

Changes the no paste flag of objects.
@c ./../src/action.c 4611

The "no paste flag" of a pad determines whether the solderpaste
 stencil will have an opening for the pad (no set) or if there wil be
 no solderpaste on the pad (set).  This is used for things such as
 fiducial pads.


@node ChangePinName Action
@subsection ChangePinName
@c key ChangePinName in hid 
@cartouche
@format
ChangePinName(ElementName,PinNumber,PinName)@end format
@end cartouche

Sets the name of a specific pin on a specific element.
@c ./../src/action.c 3924

This can be especially useful for annotating pin names from a
schematic to the layout without requiring knowledge of the pcb file
format.

@example
ChangePinName(U3, 7, VCC)
@end example


@node ChangeSize Action
@subsection ChangeSize
@c key ChangeSize in hid 
@cartouche
@format
ChangeSize(Object, delta)
ChangeSize(SelectedObjects|Selected, delta)
ChangeSize(SelectedLines|SelectedPins|SelectedVias, delta)
ChangeSize(SelectedPads|SelectedTexts|SelectedNames, delta)
ChangeSize(SelectedElements, delta)@end format
@end cartouche

Changes the size of objects.
@c ./../src/action.c 3543

For lines and arcs, this changes the width.  For pins and vias, this
changes the overall diameter of the copper annulus.  For pads, this
changes the width and, indirectly, the length.  For texts and names,
this changes the scaling factor.  For elements, this changes the width
of the silk layer lines and arcs for this element.


@node ChangeSquare Action
@subsection ChangeSquare
@c key ChangeSquare in hid 
@cartouche
@format
ChangeSquare(ToggleObject)
ChangeSquare(SelectedElements|SelectedPins)
ChangeSquare(Selected|SelectedObjects)@end format
@end cartouche

Changes the square flag of pins and pads.
@c ./../src/action.c 4250

Note that @code{Pins} means both pins and pads.

@pinshapes


@node ClearOctagon Action
@subsection ClearOctagon
@c key ClearOctagon in hid 
@cartouche
@format
ClearOctagon(ToggleObject|Object|SelectedObjects|Selected)
ClearOctagon(SelectedElements|SelectedPins|SelectedVias)@end format
@end cartouche

Clears the octagon-flag of pins and vias.
@c ./../src/action.c 4515

@pinshapes


@node ClearSquare Action
@subsection ClearSquare
@c key ClearSquare in hid 
@cartouche
@format
ClearSquare(ToggleObject|SelectedElements|SelectedPins)@end format
@end cartouche

Clears the square-flag of pins and pads.
@c ./../src/action.c 4352

Note that @code{Pins} means pins and pads.

@pinshapes


@node ClrFlag Action
@subsection ClrFlag
@c key ClrFlag in hid 
@cartouche
@format
ClrFlag(Object|Selected|SelectedObjects, flag)
ClrFlag(SelectedLines|SelectedPins|SelectedVias, flag)
ClrFlag(SelectedPads|SelectedTexts|SelectedNames, flag)
ClrFlag(SelectedElements, flag)
flag = square | octagon | thermal | join@end format
@end cartouche

Clears flags on objects.
@c ./../src/action.c 5733

Turns the given flag off, regardless of its previous setting.  See
@code{ChangeFlag}.

@example
ClrFlag(SelectedLines,join)
@end example


@node Connection Action
@subsection Connection
@c key Connection in hid 
@cartouche
@format
Connection(Find|ResetLinesAndPolygons|ResetPinsAndVias|Reset)@end format
@end cartouche

Searches connections of the object at the cursor position.
@c ./../src/action.c 2093

Connections found with this action will be highlighted in the
``connected-color'' color and will have the ``found'' flag set.

@table @code

@item Find
The net under the cursor is ``found''.

@item ResetLinesAndPolygons
Any ``found'' lines and polygons are marked ``not found''.

@item ResetPinsAndVias
Any ``found'' pins and vias are marked ``not found''.

@item Reset
All ``found'' objects are marked ``not found''.

@end table


@node Delete Action
@subsection Delete
@c key Delete in hid 
@cartouche
@format
Delete(Object|Selected)
Delete(AllRats|SelectedRats)@end format
@end cartouche

Delete stuff.
@c ./../src/action.c 3371


@node DeleteRats Action
@subsection DeleteRats
@c key DeleteRats in hid 
@cartouche
@format
DeleteRats(AllRats|Selected|SelectedRats)@end format
@end cartouche

Delete rat lines.
@c ./../src/action.c 3418


@node DisableVendor Action
@subsection DisableVendor
@c key DisableVendor in hid 
@cartouche
@format
DisableVendor()@end format
@end cartouche

Disables automatic drill size mapping.
@c ./../src/vendor.c 161

@cindex vendor map 
@cindex vendor drill table
@findex DisableVendor()

When drill mapping is enabled, new instances of pins and vias will
have their drill holes mapped to one of the allowed drill sizes
specified in the currently loaded vendor drill table.


@node DisperseElements Action
@subsection DisperseElements
@c key DisperseElements in hid 
@cartouche
@format
DisperseElements(All|Selected)@end format
@end cartouche

Disperses elements.
@c ./../src/action.c 2146

Normally this is used when starting a board, by selecting all elements
and then dispersing them.  This scatters the elements around the board
so that you can pick individual ones, rather than have all the
elements at the same 0,0 coordinate and thus impossible to choose
from.


@node Display Action
@subsection Display
@c key Display in hid 
@cartouche
@format
Display(NameOnPCB|Description|Value)
Display(Grid|Redraw)
Display(CycleClip|CycleCrosshair|Toggle45Degree|ToggleStartDirection)
Display(ToggleGrid|ToggleRubberBandMode|ToggleUniqueNames)
Display(ToggleMask|ToggleName|ToggleClearLine|ToggleFullPoly|ToggleSnapPin)
Display(ToggleThindraw|ToggleThindrawPoly|ToggleOrthoMove|ToggleLocalRef)
Display(ToggleCheckPlanes|ToggleShowDRC|ToggleAutoDRC)
Display(ToggleLiveRoute|LockNames|OnlyNames)
Display(Pinout|PinOrPadName)@end format
@end cartouche

Several display-related actions.
@c ./../src/action.c 2262

@table @code

@item NameOnPCB
@item Description
@item Value
Specify whether all elements show their name, description, or value.

@item Redraw
Redraw the whole board.

@item Toggle45Degree
When clear, lines can be drawn at any angle.  When set, lines are
restricted to multiples of 45 degrees and requested lines may be
broken up according to the clip setting.

@item CycleClip
Changes the way lines are restricted to 45 degree increments.  The
various settings are: straight only, orthogonal then angled, and angled
then orthogonal.  If AllDirections is set, this action disables it.

@item CycleCrosshair
Changes crosshair drawing.  Crosshair may accept form of 4-ray,
8-ray and 12-ray cross.

@item ToggleRubberBandMode
If set, moving an object moves all the lines attached to it too.

@item ToggleStartDirection
If set, each time you set a point in a line, the Clip toggles between
orth-angle and angle-ortho.

@item ToggleUniqueNames
If set, you will not be permitted to change the name of an element to
match that of another element.

@item ToggleSnapPin
If set, pin centers and pad end points are treated as additional grid
points that the cursor can snap to.

@item ToggleLocalRef
If set, the mark is automatically set to the beginning of any move, so
you can see the relative distance you've moved.

@item ToggleThindraw
If set, objects on the screen are drawn as outlines (lines are drawn
as center-lines).  This lets you see line endpoints hidden under pins,
for example.

@item ToggleThindrawPoly
If set, polygons on the screen are drawn as outlines.

@item ToggleShowDRC
If set, pending objects (i.e. lines you're in the process of drawing)
will be drawn with an outline showing how far away from other copper
you need to be.

@item ToggleLiveRoute
If set, the progress of the autorouter will be visible on the screen.

@item ToggleAutoDRC
If set, you will not be permitted to make connections which violate
the current DRC and netlist settings.

@item ToggleCheckPlanes
If set, lines and arcs aren't drawn, which usually leaves just the
polygons.  If you also disable all but the layer you're interested in,
this allows you to check for isolated regions.

@item ToggleOrthoMove
If set, the crosshair is only allowed to move orthogonally from its
previous position.  I.e. you can move an element or line up, down,
left, or right, but not up+left or down+right.

@item ToggleName
Selects whether the pinouts show the pin names or the pin numbers.

@item ToggleLockNames
If set, text will ignore left mouse clicks and actions that work on
objects under the mouse. You can still select text with a lasso (left
mouse drag) and perform actions on the selection.

@item ToggleOnlyNames
If set, only text will be sensitive for mouse clicks and actions that
work on objects under the mouse. You can still select other objects
with a lasso (left mouse drag) and perform actions on the selection.

@item ToggleMask
Turns the solder mask on or off.

@item ToggleClearLine
When set, the clear-line flag causes new lines and arcs to have their
``clear polygons'' flag set, so they won't be electrically connected
to any polygons they overlap.

@item ToggleFullPoly
When set, the full-poly flag causes new polygons to have their
``full polygon'' flag set, so all parts of them will be displayed
instead of only the biggest one.

@item ToggleGrid
Resets the origin of the current grid to be wherever the mouse pointer
is (not where the crosshair currently is).  If you provide two numbers
after this, the origin is set to that coordinate.

@item Grid
Toggles whether the grid is displayed or not.

@item Pinout
Causes the pinout of the element indicated by the cursor to be
displayed, usually in a separate window.

@item PinOrPadName
Toggles whether the names of pins, pads, or (yes) vias will be
displayed.  If the cursor is over an element, all of its pins and pads
are affected.

@end table


@node djopt Action
@subsection djopt
@c key djopt in hid 
@cartouche
@format
djopt(debumpify|unjaggy|simple|vianudge|viatrim|orthopull)
djopt(auto) - all of the above
djopt(miter)@end format
@end cartouche

Perform various optimizations on the current board.
@c ./../src/djopt.c 2853

The different types of optimizations change your board in order to
reduce the total trace length and via count.

@table @code

@item debumpify
Looks for U-shaped traces that can be shortened or eliminated.

@item unjaggy
Looks for corners which could be flipped to eliminate one or more
corners (i.e. jaggy lines become simpler).

@item simple
Removing uneeded vias, replacing two or more trace segments in a row
with a single segment.  This is usually performed automatically after
other optimizations.

@item vianudge
Looks for vias where all traces leave in the same direction.  Tries to
move via in that direction to eliminate one of the traces (and thus a
corner).

@item viatrim
Looks for traces that go from via to via, where moving that trace to a
different layer eliminates one or both vias.

@item orthopull
Looks for chains of traces all going in one direction, with more
traces orthogonal on one side than on the other.  Moves the chain in
that direction, causing a net reduction in trace length, possibly
eliminating traces and/or corners.

@item splitlines
Looks for lines that pass through vias, pins, or pads, and splits them
into separate lines so they can be managed separately.

@item auto
Performs the above options, repeating until no further optimizations
can be made.

@item miter
Replaces 90 degree corners with a pair of 45 degree corners, to reduce
RF losses and trace length.

@end table


@node DRC Action
@subsection DRC
@c key DRC in hid 
@cartouche
@format
DRC()@end format
@end cartouche

Invoke the DRC check.
@c ./../src/action.c 1755

Note that the design rule check uses the current board rule settings,
not the current style settings.


@node DumpLibrary Action
@subsection DumpLibrary
@c key DumpLibrary in hid 
@cartouche
@format
DumpLibrary()@end format
@end cartouche

Display the entire contents of the libraries.
@c ./../src/action.c 1791



@node elementlist Action
@subsection elementlist
@c key elementlist in hid 
@cartouche
@format
ElementList(Start|Done|Need,<refdes>,<footprint>,<value>)@end format
@end cartouche

Adds the given element if it doesn't already exist.
@c ./../src/action.c 5983

@table @code

@item Start
Indicates the start of an element list; call this before any Need
actions.

@item Need
Searches the board for an element with a matching refdes.

If found, the value and footprint are updated.

If not found, a new element is created with the given footprint and value.

@item Done
Compares the list of elements needed since the most recent
@code{start} with the list of elements actually on the board.  Any
elements that weren't listed are selected, so that the user may delete
them.

@end table


@node elementsetattr Action
@subsection elementsetattr
@c key elementsetattr in hid 
@cartouche
@format
ElementSetAttr(refdes,name[,value])@end format
@end cartouche

Sets or clears an element-specific attribute.
@c ./../src/action.c 6176

If a value is specified, the named attribute is added (if not already
present) or changed (if it is) to the given value.  If the value is
not specified, the given attribute is removed if present.


@node EnableVendor Action
@subsection EnableVendor
@c key EnableVendor in hid 
@cartouche
@format
EnableVendor()@end format
@end cartouche

Enables automatic drill size mapping.
@c ./../src/vendor.c 146

@cindex vendor map 
@cindex vendor drill table
@findex EnableVendor()

When drill mapping is enabled, new instances of pins and vias will
have their drill holes mapped to one of the allowed drill sizes
specified in the currently loaded vendor drill table.  To enable drill
mapping, a vendor resource file containing a drill table must be
loaded first.


@node execcommand Action
@subsection execcommand
@c key execcommand in hid 
@cartouche
@format
ExecCommand(command)@end format
@end cartouche

Runs a command.
@c ./../src/action.c 6234

Runs the given command, which is a system executable.


@node ExecuteFile Action
@subsection ExecuteFile
@c key ExecuteFile in hid 
@cartouche
@format
ExecuteFile(filename)@end format
@end cartouche

Run actions from the given file.
@c ./../src/action.c 5861

Lines starting with @code{#} are ignored.


@node Flip Action
@subsection Flip
@c key Flip in hid 
@cartouche
@format
Flip(Object|Selected|SelectedElements)@end format
@end cartouche

Flip an element to the opposite side of the board.
@c ./../src/action.c 1841

Note that the location of the element will be symmetric about the
cursor location; i.e. if the part you are pointing at will still be at
the same spot once the element is on the other side.  When flipping
multiple elements, this retains their positions relative to each
other, not their absolute positions on the board.


@node FontEdit Action
@subsection FontEdit
@c key FontEdit in hid 
@cartouche
@format
FontEdit()@end format
@end cartouche

Convert the current font to a PCB for editing.
@c ./../src/fontmode.c 73


@node FontSave Action
@subsection FontSave
@c key FontSave in hid 
@cartouche
@format
FontSave()@end format
@end cartouche

Convert the current PCB back to a font.
@c ./../src/fontmode.c 173


@node FreeRotateBuffer Action
@subsection FreeRotateBuffer
@c key FreeRotateBuffer in hid 
@cartouche
@format
FreeRotateBuffer([Angle])@end format
@end cartouche

Rotates the current paste buffer contents by the specified angle.  The
angle is given in degrees.  If no angle is given, the user is prompted
for one.

@c ./../src/buffer.c 1370
   
Rotates the contents of the pastebuffer by an arbitrary angle.  If no
angle is given, the user is prompted for one.


@node GlobalPuller Action
@subsection GlobalPuller
@c key GlobalPuller in hid 
@cartouche
@format
GlobalPuller()@end format
@end cartouche

Pull all traces tight.
@c ./../src/puller.c 534


@node h Action
@subsection h
@c key h in hid 
@cartouche
@format
h@end format
@end cartouche

Print a help message for commands.
@c ./../src/command.c 72

@colonaction


@node Import Action
@subsection Import
@c key Import in hid 
@cartouche
@format
Import()
Import([gnetlist|make[,source,source,...]])
Import(setnewpoint[,(mark|center|X,Y)])
Import(setdisperse,D,units)
@end format
@end cartouche

Import schematics.
@c ./../src/action.c 6464

Imports element and netlist data from the schematics (or some other
source).  The first parameter, which is optional, is the mode.  If not
specified, the @code{import::mode} attribute in the PCB is used.
@code{gnetlist} means gnetlist is used to obtain the information from
the schematics.  @code{make} invokes @code{make}, assuming the user
has a @code{Makefile} in the current directory.  The @code{Makefile}
will be invoked with the following variables set:

@table @code

@item PCB
The name of the .pcb file

@item SRCLIST
A space-separated list of source files

@item OUT
The name of the file in which to put the command script, which may
contain any @pcb{} actions.  By default, this is a temporary file
selected by @pcb{}, but if you specify an @code{import::outfile}
attribute, that file name is used instead (and not automatically
deleted afterwards).

@end table

The target specified to be built is the first of these that apply:

@itemize @bullet

@item
The target specified by an @code{import::target} attribute.

@item
The output file specified by an @code{import::outfile} attribute.

@item
If nothing else is specified, the target is @code{pcb_import}.

@end itemize

If you specify an @code{import::makefile} attribute, then "-f <that
file>" will be added to the command line.

If you specify the mode, you may also specify the source files
(schematics).  If you do not specify any, the list of schematics is
obtained by reading the @code{import::src@var{N}} attributes (like
@code{import::src0}, @code{import::src1}, etc).

For compatibility with future extensions to the import file format,
the generated file @emph{must not} start with the two characters
@code{#%}.

If a temporary file is needed the @code{TMPDIR} environment variable
is used to select its location.

Note that the programs @code{gnetlist} and @code{make} may be
overridden by the user via the @code{make-program} and @code{gnetlist}
@code{pcb} settings (i.e. in @code{~/.pcb/settings} or on the command
line).

If @pcb{} cannot determine which schematic(s) to import from, the GUI
is called to let user choose (see @code{ImportGUI()}).

Note that Import() doesn't delete anything - after an Import, elements
which shouldn't be on the board are selected and may be removed once
it's determined that the deletion is appropriate.

If @code{Import()} is called with @code{setnewpoint}, then the location
of new components can be specified.  This is where parts show up when
they're added to the board.  The default is the center of the board.

@table @code

@item Import(setnewpoint)

Prompts the user to click on the board somewhere, uses that point.  If
called by a hotkey, uses the current location of the crosshair.

@item Import(setnewpoint,mark)

Uses the location of the mark.  If no mark is present, the point is
not changed.

@item Import(setnewpoint,center)

Resets the point to the center of the board.

@item Import(setnewpoint,X,Y,units)

Sets the point to the specific coordinates given.  Example:
@code{Import(setnewpoint,50,25,mm)}

@end table

Note that the X and Y locations are stored in attributes named
@code{import::newX} and @code{import::newY} so you could change them
manually if you wished.

Calling @code{Import(setdisperse,D,units)} sets how much the newly
placed elements are dispersed relative to the set point.  For example,
@code{Import(setdisperse,10,mm)} will offset each part randomly up to
10mm away from the point.  The default dispersion is 1/10th of the
smallest board dimension.  Dispersion is saved in the
@code{import::disperse} attribute.


@node l Action
@subsection l
@c key l in hid 
@cartouche
@format
l [name]@end format
@end cartouche

Loads layout data.
@c ./../src/command.c 99

Loads a new datafile (layout) and, if confirmed, overwrites any
existing unsaved data.  The filename and the searchpath
(@emph{filePath}) are passed to the command defined by
@emph{fileCommand}.  If no filename is specified a file select box
will popup.

@colonaction


@node le Action
@subsection le
@c key le in hid 
@cartouche
@format
le [name]@end format
@end cartouche

Loads an element into the current buffer.
@c ./../src/command.c 129

The filename and the searchpath (@emph{elementPath}) are passed to the
command defined by @emph{elementCommand}.  If no filename is specified
a file select box will popup.

@colonaction


@node LoadFootprint Action
@subsection LoadFootprint
@c key LoadFootprint in hid 
@cartouche
@format
LoadFootprint(filename[,refdes,value])@end format
@end cartouche

Loads a single footprint by name.
@c ./../src/buffer.c 809

Loads a single footprint by name, rather than by reference or through
the library.  If a refdes and value are specified, those are inserted
into the footprint as well.  The footprint remains in the paste buffer.


@node LoadFrom Action
@subsection LoadFrom
@c key LoadFrom in hid 
@cartouche
@format
LoadFrom(Layout|LayoutToBuffer|ElementToBuffer|Netlist|Revert,filename)@end format
@end cartouche

Load layout data from a file.
@c ./../src/action.c 5031

This action assumes you know what the filename is.  The various GUIs
should have a similar @code{Load} action where the filename is
optional, and will provide their own file selection mechanism to let
you choose the file name.

@table @code

@item Layout
Loads an entire PCB layout, replacing the current one.

@item LayoutToBuffer
Loads an entire PCB layout to the paste buffer.

@item ElementToBuffer
Loads the given element file into the paste buffer.  Element files
contain only a single @code{Element} definition, such as the
``newlib'' library uses.

@item Netlist
Loads a new netlist, replacing any current netlist.

@item Revert
Re-loads the current layout from its disk file, reverting any changes
you may have made.

@end table


@node LoadVendorFrom Action
@subsection LoadVendorFrom
@c key LoadVendorFrom in hid 
@cartouche
@format
LoadVendorFrom(filename)@end format
@end cartouche

Loads the specified vendor resource file.
@c ./../src/vendor.c 201

@cindex vendor map 
@cindex vendor drill table
@findex LoadVendorFrom()

@table @var
@item filename
Name of the vendor resource file.  If not specified, the user will
be prompted to enter one.
@end table


@node m Action
@subsection m
@c key m in hid 
@cartouche
@format
m [name]@end format
@end cartouche

Loads a layout into the current buffer.
@c ./../src/command.c 157

The filename and the searchpath (@emph{filePath}) are passed to the
command defined by @emph{fileCommand}.
If no filename is specified a file select box will popup.

@colonaction


@node MarkCrosshair Action
@subsection MarkCrosshair
@c key MarkCrosshair in hid 
@cartouche
@format
MarkCrosshair()
MarkCrosshair(Center)@end format
@end cartouche

Set/Reset the Crosshair mark.
@c ./../src/action.c 3502

The ``mark'' is a small X-shaped target on the display which is
treated like a second origin (the normal origin is the upper let
corner of the board).  The GUI will display a second set of
coordinates for this mark, which tells you how far you are from it.

If no argument is given, the mark is toggled - disabled if it was
enabled, or enabled at the current cursor position of disabled.  If
the @code{Center} argument is given, the mark is moved to the current
cursor location.


@node Message Action
@subsection Message
@c key Message in hid 
@cartouche
@format
Message(message)@end format
@end cartouche

Writes a message to the log window.
@c ./../src/action.c 1886

This action displays a message to the log window.  This action is primarily
provided for use by other programs which may interface with PCB.  If
multiple arguments are given, each one is sent to the log window
followed by a newline.


@node MinClearGap Action
@subsection MinClearGap
@c key MinClearGap in hid 
@cartouche
@format
MinClearGap(delta)
MinClearGap(Selected, delta)@end format
@end cartouche

Ensures that polygons are a minimum distance from objects.
@c ./../src/action.c 3827

Checks all specified objects, and increases the polygon clearance if
needed to ensure a minimum distance between their edges and the
polygon edges.


@node MinMaskGap Action
@subsection MinMaskGap
@c key MinMaskGap in hid 
@cartouche
@format
MinMaskGap(delta)
MinMaskGap(Selected, delta)@end format
@end cartouche

Ensures the mask is a minimum distance from pins and pads.
@c ./../src/action.c 3752

Checks all specified pins and/or pads, and increases the mask if
needed to ensure a minimum distance between the pin or pad edge and
the mask edge.


@node Mode Action
@subsection Mode
@c key Mode in hid 
@cartouche
@format
Mode(Arc|Arrow|Copy|InsertPoint|Line|Lock|Move|None|PasteBuffer)
Mode(Polygon|Rectangle|Remove|Rotate|Text|Thermal|Via)
Mode(Notify|Release|Cancel|Stroke)
Mode(Save|Restore)@end format
@end cartouche

Change or use the tool mode.
@c ./../src/action.c 2612

@table @code

@item Arc
@itemx Arrow
@itemx Copy
@itemx InsertPoint
@itemx Line
@itemx Lock
@itemx Move
@itemx None
@itemx PasteBuffer
@itemx Polygon
@itemx Rectangle
@itemx Remove
@itemx Rotate
@itemx Text
@itemx Thermal
@itemx Via
Select the indicated tool.

@item Notify
Called when you press the mouse button, or move the mouse.

@item Release
Called when you release the mouse button.

@item Cancel
Cancels any pending tool activity, allowing you to restart elsewhere.
For example, this allows you to start a new line rather than attach a
line to the previous line.

@item Escape
Similar to Cancel but calling this action a second time will return
to the Arrow tool.

@item Stroke
If your @code{pcb} was built with libstroke, this invokes the stroke
input method.  If not, this will restart a drawing mode if you were
drawing, else it will select objects.

@item Save
Remembers the current tool.

@item Restore
Restores the tool to the last saved tool.

@end table


@node MorphPolygon Action
@subsection MorphPolygon
@c key MorphPolygon in hid 
@cartouche
@format
MorphPolygon(Object|Selected)@end format
@end cartouche

Converts dead polygon islands into separate polygons.
@c ./../src/action.c 4087

If a polygon is divided into unconnected "islands", you can use
this command to convert the otherwise disappeared islands into
separate polygons. Be sure the cursor is over a portion of the
polygon that remains visible. Very small islands that may flake
off are automatically deleted.


@node MoveLayer Action
@subsection MoveLayer
@c key MoveLayer in hid 
@cartouche
@format
MoveLayer(old,new)@end format
@end cartouche

Moves/Creates/Deletes Layers.
@c ./../src/move.c 1091

Moves a layer, creates a new layer, or deletes a layer.

@table @code

@item old
The is the layer number to act upon.  Allowed values are:
@table @code

@item c
Currently selected layer.

@item -1
Create a new layer.

@item number
An existing layer number.

@end table

@item new
Specifies where to move the layer to.  Allowed values are:
@table @code
@item -1
Deletes the layer.

@item up
Moves the layer up.

@item down
Moves the layer down.

@item c
Creates a new layer.

@end table

@end table


@node MoveObject Action
@subsection MoveObject
@c key MoveObject in hid 
@cartouche
@format
MoveObject(X,Y,dim)@end format
@end cartouche

Moves the object under the crosshair.
@c ./../src/action.c 5567

The @code{X} and @code{Y} are treated like @code{delta} is for many
other objects.  For each, if it's prefixed by @code{+} or @code{-},
then that amount is relative.  Otherwise, it's absolute.  Units can be
@code{mil} or @code{mm}; if unspecified, units are PCB's internal
units, currently 1/100 mil.


@node MoveToCurrentLayer Action
@subsection MoveToCurrentLayer
@c key MoveToCurrentLayer in hid 
@cartouche
@format
MoveToCurrentLayer(Object|SelectedObjects)@end format
@end cartouche

Moves objects to the current layer.
@c ./../src/action.c 5609

Note that moving an element from a component layer to a solder layer,
or from solder to component, won't automatically flip it.  Use the
@code{Flip()} action to do that.


@node Netlist Action
@subsection Netlist
@c key Netlist in hid 
@cartouche
@format
Net(find|select|rats|norats|clear[,net[,pin]])
Net(freeze|thaw|forcethaw)
Net(add,net,pin)@end format
@end cartouche

Perform various actions on netlists.
@c ./../src/netlist.c 289

Each of these actions apply to a specified set of nets.  @var{net} and
@var{pin} are patterns which match one or more nets or pins; these
patterns may be full names or regular expressions.  If an exact match
is found, it is the only match; if no exact match is found,
@emph{then} the pattern is tried as a regular expression.

If neither @var{net} nor @var{pin} are specified, all nets apply.  If
@var{net} is specified but not @var{pin}, all nets matching @var{net}
apply.  If both are specified, nets which match @var{net} and contain
a pin matching @var{pin} apply.

@table @code

@item find
Nets which apply are marked @emph{found} and are drawn in the
@code{connected-color} color.

@item select
Nets which apply are selected.

@item rats
Nets which apply are marked as available for the rats nest.

@item norats
Nets which apply are marked as not available for the rats nest.

@item clear
Clears the netlist.

@item add
Add the given pin to the given netlist, creating either if needed.

@item sort
Called after a list of add's, this sorts the netlist.

@item freeze
@itemx thaw
@itemx forcethaw
Temporarily prevents changes to the netlist from being reflected in
the GUI.  For example, if you need to make multiple changes, you
freeze the netlist, make the changes, then thaw it.  Note that
freeze/thaw requests may nest, with the netlist being fully thawed
only when all pending freezes are thawed.  You can bypass the nesting
by using forcethaw, which resets the freeze count and immediately
updates the GUI.

@end table


@node New Action
@subsection New
@c key New in hid 
@cartouche
@format
New([name])@end format
@end cartouche

Starts a new layout.
@c ./../src/action.c 5093

If a name is not given, one is prompted for.


@node OptAutoOnly Action
@subsection OptAutoOnly
@c key OptAutoOnly in hid 
@cartouche
@format
OptAutoOnly()@end format
@end cartouche

Toggles the optimize-only-autorouted flag.
@c ./../src/djopt.c 129

The original purpose of the trace optimizer was to clean up the traces
created by the various autorouters that have been used with PCB.  When
a board has a mix of autorouted and carefully hand-routed traces, you
don't normally want the optimizer to move your hand-routed traces.
But, sometimes you do.  By default, the optimizer only optimizes
autorouted traces.  This action toggles that setting, so that you can
optimize hand-routed traces also.


@node PasteBuffer Action
@subsection PasteBuffer
@c key PasteBuffer in hid 
@cartouche
@format
PasteBuffer(AddSelected|Clear|1..MAX_BUFFER)
PasteBuffer(Rotate, 1..3)
PasteBuffer(Convert|Save|Restore|Mirror)
PasteBuffer(ToLayout, X, Y, units)@end format
@end cartouche

Various operations on the paste buffer.
@c ./../src/action.c 5153

There are a number of paste buffers; the actual limit is a
compile-time constant @code{MAX_BUFFER} in @file{globalconst.h}.  It
is currently @code{5}.  One of these is the ``current'' paste buffer,
often referred to as ``the'' paste buffer.

@table @code

@item AddSelected
Copies the selected objects to the current paste buffer.

@item Clear
Remove all objects from the current paste buffer.

@item Convert
Convert the current paste buffer to an element.  Vias are converted to
pins, lines are converted to pads.

@item Restore
Convert any elements in the paste buffer back to vias and lines.

@item Mirror
Flip all objects in the paste buffer vertically (up/down flip).  To mirror
horizontally, combine this with rotations.

@item Rotate
Rotates the current buffer.  The number to pass is 1..3, where 1 means
90 degrees counter clockwise, 2 means 180 degrees, and 3 means 90
degrees clockwise (270 CCW).

@item Save
Saves any elements in the current buffer to the indicated file.

@item ToLayout
Pastes any elements in the current buffer to the indicated X, Y
coordinates in the layout.  The @code{X} and @code{Y} are treated like
@code{delta} is for many other objects.  For each, if it's prefixed by
@code{+} or @code{-}, then that amount is relative to the last
location.  Otherwise, it's absolute.  Units can be
@code{mil} or @code{mm}; if unspecified, units are PCB's internal
units, currently 1/100 mil.


@item 1..MAX_BUFFER
Selects the given buffer to be the current paste buffer.

@end table


@node Polygon Action
@subsection Polygon
@c key Polygon in hid 
@cartouche
@format
Polygon(Close|PreviousPoint)@end format
@end cartouche

Some polygon related stuff.
@c ./../src/action.c 5503

Polygons need a special action routine to make life easier.

@table @code

@item Close
Creates the final segment of the polygon.  This may fail if clipping
to 45 degree lines is switched on, in which case a warning is issued.

@item PreviousPoint
Resets the newly entered corner to the previous one. The Undo action
will call Polygon(PreviousPoint) when appropriate to do so.

@end table


@node Puller Action
@subsection Puller
@c key Puller in hid 
@cartouche
@format
Puller()@end format
@end cartouche

Pull an arc-line junction tight.
@c ./../src/puller.c 411

The @code{Puller()} action is a special-purpose optimization.  When
invoked while the crosshair is over the junction of an arc and a line,
it will adjust the arc's angle and the connecting line's endpoint such
that the line intersects the arc at a tangent.  In the example below,
the left side is ``before'' with the black target marking where to put
the crosshair:

@center @image{puller,,,Example of how puller works,png}

The right side is ``after'' with the black target marking where the
arc-line intersection was moved to.


@node q Action
@subsection q
@c key q in hid 
@cartouche
@format
q@end format
@end cartouche

Quits the application after confirming.
@c ./../src/command.c 185

If you have unsaved changes, you will be prompted to confirm (or
save) before quitting.

@colonaction


@node q! Action
@subsection q!
@c key q! in hid 
@cartouche
@format
q!@end format
@end cartouche

Quits the application without confirming.
@c ./../src/command.c 199

Note that this command neither saves your data nor prompts for
confirmation.

@colonaction


@node Quit Action
@subsection Quit
@c key Quit in hid 
@cartouche
@format
Quit()@end format
@end cartouche

Quits the application after confirming.
@c ./../src/action.c 2071

If you have unsaved changes, you will be prompted to confirm (or
save) before quitting.


@node Redo Action
@subsection Redo
@c key Redo in hid 
@cartouche
@format
Redo()@end format
@end cartouche

Redo recent``undo''operations.
@c ./../src/action.c 5468

This routine allows you to recover from the last undo command.  You
might want to do this if you thought that undo was going to revert
something other than what it actually did (in case you are confused
about which operations are un-doable), or if you have been backing up
through a long undo list and over-shoot your stopping point.  Any
change that is made since the undo in question will trim the redo
list.  For example if you add ten lines, then undo three of them you
could use redo to put them back, but if you move a line on the board
before performing the redo, you will lose the ability to "redo" the
three "undone" lines.


@node RemoveSelected Action
@subsection RemoveSelected
@c key RemoveSelected in hid 
@cartouche
@format
RemoveSelected()@end format
@end cartouche

Removes any selected objects.
@c ./../src/action.c 2832


@node Renumber Action
@subsection Renumber
@c key Renumber in hid 
@cartouche
@format
Renumber()
Renumber(filename)@end format
@end cartouche

Renumber all elements.  The changes will be recorded to filename
for use in backannotating these changes to the schematic.
@c ./../src/action.c 2848


@node Report Action
@subsection Report
@c key Report in hid 
@cartouche
@format
Report(Object|DrillReport|FoundPins|NetLength|AllNetLengths|[,name])@end format
@end cartouche

Produce various report.
@c ./../src/report.c 942

@table @code

@item Object
The object under the crosshair will be reported, describing various
aspects of the object.

@item DrillReport
A report summarizing the number of drill sizes used, and how many of
each, will be produced.

@item FoundPins
A report listing all pins and pads which are marked as ``found'' will
be produced.

@item NetLength
The name and length of the net under the crosshair will be reported to
the message log.

@item AllNetLengths
The name and length of the net under the crosshair will be reported to
the message log.  An optional parameter specifies mm, mil, pcb, or in
units

@end table


@node ReportDialog Action
@subsection ReportDialog
@c key ReportDialog in hid 
@cartouche
@format
ReportDialog()@end format
@end cartouche

Report on the object under the crosshair
@c ./../src/report.c 125

This is a shortcut for @code{Report(Object)}.


@node RipUp Action
@subsection RipUp
@c key RipUp in hid 
@cartouche
@format
RipUp(All|Selected|Element)@end format
@end cartouche

Ripup auto-routed tracks, or convert an element to parts.
@c ./../src/action.c 3199

@table @code

@item All
Removes all lines and vias which were created by the autorouter.

@item Selected
Removes all selected lines and vias which were created by the
autorouter.

@item Element
Converts the element under the cursor to parts (vias and lines).  Note
that this uses the highest numbered paste buffer.

@end table


@node rn Action
@subsection rn
@c key rn in hid 
@cartouche
@format
rn [name]@end format
@end cartouche

Reads netlist.
@c ./../src/command.c 214

If no filename is given a file select box will pop up.  The file is
read via the command defined by the @emph{RatCommand} resource. The
command must send its output to @emph{stdout}.

Netlists are used for generating rat's nests (see @ref{Rats Nest}) and
for verifying the board layout (which is also accomplished by the
@emph{Ratsnest} command).

@colonaction


@node RouteStyle Action
@subsection RouteStyle
@c key RouteStyle in hid 
@cartouche
@format
RouteStyle(1|2|3|4)@end format
@end cartouche

Copies the indicated routing style into the current sizes.
@c ./../src/action.c 5535


@node s Action
@subsection s
@c key s in hid 
@cartouche
@format
s [name]@end format
@end cartouche

Saves layout data.
@c ./../src/command.c 244

Data and the filename are passed to the command defined by the
resource @emph{saveCommand}. It must read the layout data from
@emph{stdin}.  If no filename is entered, either the last one is used
again or, if it is not available, a file select box will pop up.

@colonaction


@node SaveSettings Action
@subsection SaveSettings
@c key SaveSettings in hid 
@cartouche
@format
SaveSettings()
SaveSettings(local)@end format
@end cartouche

Saves settings.
@c ./../src/action.c 5015

If you pass no arguments, the settings are stored in
@code{$HOME/.pcb/settings}.  If you pass the word @code{local} they're
saved in @code{./pcb.settings}.


@node SaveTo Action
@subsection SaveTo
@c key SaveTo in hid 
@cartouche
@format
SaveTo(Layout|LayoutAs,filename)
SaveTo(AllConnections|AllUnusedPins|ElementConnections,filename)
SaveTo(PasteBuffer,filename)@end format
@end cartouche

Saves data to a file.
@c ./../src/action.c 4919

@table @code

@item Layout
Saves the current layout.

@item LayoutAs
Saves the current layout, and remembers the filename used.

@item AllConnections
Save all connections to a file.

@item AllUnusedPins
List all unused pins to a file.

@item ElementConnections
Save connections to the element at the cursor to a file.

@item PasteBuffer
Save the content of the active Buffer to a file. This is the graphical way to create a footprint.

@end table


@node Select Action
@subsection Select
@c key Select in hid 
@cartouche
@format
Select(Object|ToggleObject)
Select(All|Block|Connection)
Select(ElementByName|ObjectByName|PadByName|PinByName)
Select(ElementByName|ObjectByName|PadByName|PinByName, Name)
Select(TextByName|ViaByName|NetByName)
Select(TextByName|ViaByName|NetByName, Name)
Select(Convert)@end format
@end cartouche

Toggles or sets the selection.
@c ./../src/action.c 4651

@table @code

@item ElementByName
@item ObjectByName
@item PadByName
@item PinByName
@item TextByName
@item ViaByName
@item NetByName

These all rely on having a regular expression parser built into
@code{pcb}.  If the name is not specified then the user is prompted
for a pattern, and all objects that match the pattern and are of the
type specified are selected.

@item Object
@item ToggleObject
Selects the object under the cursor.

@item Block
Selects all objects in a rectangle indicated by the cursor.

@item All
Selects all objects on the board.

@item Connection
Selects all connections with the ``found'' flag set.

@item Convert
Converts the selected objects to an element.  This uses the highest
numbered paste buffer.

@end table


@node SetFlag Action
@subsection SetFlag
@c key SetFlag in hid 
@cartouche
@format
SetFlag(Object|Selected|SelectedObjects, flag)
SetFlag(SelectedLines|SelectedPins|SelectedVias, flag)
SetFlag(SelectedPads|SelectedTexts|SelectedNames, flag)
SetFlag(SelectedElements, flag)
flag = square | octagon | thermal | join@end format
@end cartouche

Sets flags on objects.
@c ./../src/action.c 5716

Turns the given flag on, regardless of its previous setting.  See
@code{ChangeFlag}.

@example
SetFlag(SelectedPins,thermal)
@end example


@node SetOctagon Action
@subsection SetOctagon
@c key SetOctagon in hid 
@cartouche
@format
SetOctagon(Object|ToggleObject|SelectedElements|Selected)@end format
@end cartouche

Sets the octagon-flag of objects.
@c ./../src/action.c 4459

@pinshapes


@node SetSame Action
@subsection SetSame
@c key SetSame in hid 
@cartouche
@format
SetSame()@end format
@end cartouche

Sets current layer and sizes to match indicated item.
@c ./../src/action.c 5648

When invoked over any line, arc, polygon, or via, this changes the
current layer to be the layer that item is on, and changes the current
sizes (thickness, keepaway, drill, etc) according to that item.


@node SetSquare Action
@subsection SetSquare
@c key SetSquare in hid 
@cartouche
@format
SetSquare(ToggleObject|SelectedElements|SelectedPins)@end format
@end cartouche

sets the square-flag of objects.
@c ./../src/action.c 4301

Note that @code{Pins} means pins and pads.

@pinshapes


@node SetThermal Action
@subsection SetThermal
@c key SetThermal in hid 
@cartouche
@format
SetThermal(Object|SelectedPins|SelectedVias|Selected, Style)@end format
@end cartouche

Set the thermal (on the current layer) of pins or vias to the given style.
Style = 0 means no thermal.
Style = 1 has diagonal fingers with sharp edges.
Style = 2 has horizontal and vertical fingers with sharp edges.
Style = 3 is a solid connection to the plane.Style = 4 has diagonal fingers with rounded edges.
Style = 5 has horizontal and vertical fingers with rounded edges.

@c ./../src/action.c 1912

This changes how/whether pins or vias connect to any rectangle or polygon
on the current layer. The first argument can specify one object, or all
selected pins, or all selected vias, or all selected pins and vias.
The second argument specifies the style of connection.
There are 5 possibilities:
0 - no connection,
1 - 45 degree fingers with sharp edges,
2 - horizontal & vertical fingers with sharp edges,
3 - solid connection,
4 - 45 degree fingers with rounded corners,
5 - horizontal & vertical fingers with rounded corners.

Pins and Vias may have thermals whether or not there is a polygon available 
to connect with. However, they will have no effect without the polygon.

@node SetValue Action
@subsection SetValue
@c key SetValue in hid 
@cartouche
@format
SetValue(Grid|Line|LineSize|Text|TextScale|ViaDrillingHole|Via|ViaSize, delta)@end format
@end cartouche

Change various board-wide values and sizes.
@c ./../src/action.c 1996

@table @code

@item ViaDrillingHole
Changes the diameter of the drill for new vias.

@item Grid
Sets the grid spacing.

@item Line
@item LineSize
Changes the thickness of new lines.

@item Via
@item ViaSize
Changes the diameter of new vias.

@item Text
@item TextScale
Changes the size of new text.

@end table


@node ToggleHideName Action
@subsection ToggleHideName
@c key ToggleHideName in hid 
@cartouche
@format
ToggleHideName(Object|SelectedElements)@end format
@end cartouche

Toggles the visibility of element names.
@c ./../src/action.c 4134

If names are hidden you won't see them on the screen and they will not
appear on the silk layer when you print the layout.


@node ToggleVendor Action
@subsection ToggleVendor
@c key ToggleVendor in hid 
@cartouche
@format
ToggleVendor()@end format
@end cartouche

Toggles the state of automatic drill size mapping.
@c ./../src/vendor.c 128

@cindex vendor map 
@cindex vendor drill table
@findex ToggleVendor()

When drill mapping is enabled, new instances of pins and vias will
have their drill holes mapped to one of the allowed drill sizes
specified in the currently loaded vendor drill table.  To enable drill
mapping, a vendor resource file containing a drill table must be
loaded first.


@node Undo Action
@subsection Undo
@c key Undo in hid 
@cartouche
@format
Undo()
Undo(ClearList)@end format
@end cartouche

Undo recent changes.
@c ./../src/action.c 5304

The unlimited undo feature of @code{Pcb} allows you to recover from
most operations that materially affect you work.  Calling
@code{Undo()} without any parameter recovers from the last (non-undo)
operation. @code{ClearList} is used to release the allocated
memory. @code{ClearList} is called whenever a new layout is started or
loaded. See also @code{Redo} and @code{Atomic}.

Note that undo groups operations by serial number; changes with the
same serial number will be undone (or redone) as a group.  See
@code{Atomic}.


@node UnloadVendor Action
@subsection UnloadVendor
@c key UnloadVendor in hid 
@cartouche
@format
UnloadVendor()@end format
@end cartouche

Unloads the current vendor drill mapping table.
@c ./../src/vendor.c 176

@cindex vendor map 
@cindex vendor drill table
@findex UnloadVendor()


@node Unselect Action
@subsection Unselect
@c key Unselect in hid 
@cartouche
@format
Unselect(All|Block|Connection)
Unselect(ElementByName|ObjectByName|PadByName|PinByName)
Unselect(ElementByName|ObjectByName|PadByName|PinByName, Name)
Unselect(TextByName|ViaByName)
Unselect(TextByName|ViaByName, Name)
@end format
@end cartouche

Unselects the object at the pointer location or the specified objects.
@c ./../src/action.c 4803

@table @code

@item All
Unselect all objects.

@item Block
Unselect all objects in a rectangle given by the cursor.

@item Connection
Unselect all connections with the ``found'' flag set.

@item ElementByName
@item ObjectByName
@item PadByName
@item PinByName
@item TextByName
@item ViaByName

These all rely on having a regular expression parser built into
@code{pcb}.  If the name is not specified then the user is prompted
for a pattern, and all objects that match the pattern and are of the
type specified are unselected.


@end table


@node w Action
@subsection w
@c key w in hid 
@cartouche
@format
w [name]@end format
@end cartouche

Saves layout data.
@c ./../src/command.c 250

This commands has been added for the convenience of @code{vi} users
and has the same functionality as @code{s}.

@colonaction


@node wq Action
@subsection wq
@c key wq in hid 
@cartouche
@format
wq@end format
@end cartouche

Saves the layout data and quits.
@c ./../src/command.c 291

This command has been added for the convenience of @code{vi} users and
has the same functionality as @code{s} combined with @code{q}.

@colonaction


@node common actions
@section common actions
@c ./../src/hid/common/actions.c 425

@macro hidaction

This is one of a number of actions which are part of the HID
interface.  The core functions use these actions to tell the current
GUI when to change the presented information in response to changes
that the GUI may not know about.  The user normally does not invoke
these directly.

@end macro

@menu
* LayersChanged Action:: Tells the GUI that the layers have changed.
* LibraryChanged Action:: Tells the GUI that the libraries have changed.
* NetlistChanged Action:: Tells the GUI that the netlist has changed.
* PCBChanged Action:: Tells the GUI that the whole PCB has changed. The optional``revert"parameter can be used as a hint to the GUI that the same design is beingreloaded, and that it might keep some viewport settings
* RouteStylesChanged Action:: Tells the GUI that the routing styles have changed.
@end menu
@node LayersChanged Action
@subsection LayersChanged
@c key LayersChanged in hid common
@cartouche
@format
LayersChanged()@end format
@end cartouche

Tells the GUI that the layers have changed.
@c ./../src/hid/common/actions.c 446

This includes layer names, colors, stacking order, visibility, etc.

@hidaction


@node LibraryChanged Action
@subsection LibraryChanged
@c key LibraryChanged in hid common
@cartouche
@format
LibraryChanged()@end format
@end cartouche

Tells the GUI that the libraries have changed.
@c ./../src/hid/common/actions.c 451

@hidaction


@node NetlistChanged Action
@subsection NetlistChanged
@c key NetlistChanged in hid common
@cartouche
@format
NetlistChanged()@end format
@end cartouche

Tells the GUI that the netlist has changed.
@c ./../src/hid/common/actions.c 441

@hidaction


@node PCBChanged Action
@subsection PCBChanged
@c key PCBChanged in hid common
@cartouche
@format
PCBChanged([revert])@end format
@end cartouche

Tells the GUI that the whole PCB has changed. The optional``revert"parameter can be used as a hint to the GUI that the same design is beingreloaded, and that it might keep some viewport settings
@c ./../src/hid/common/actions.c 431

@hidaction


@node RouteStylesChanged Action
@subsection RouteStylesChanged
@c key RouteStylesChanged in hid common
@cartouche
@format
RouteStylesChanged()@end format
@end cartouche

Tells the GUI that the routing styles have changed.
@c ./../src/hid/common/actions.c 436

@hidaction


@node gtk actions
@section gtk actions
@menu
* gtk About Action:: N_("Tell the user about this version of PCB.");
* gtk AdjustStyle Action:: Open the window which allows editing of the route styles.
* gtk Center Action:: N_("Moves the pointer to the center of the window.");
* gtk Cursor Action:: N_("Move the cursor.");
* gtk DoWindows Action:: N_("Open various GUI windows.");
* gtk EditLayerGroups Action:: Open the preferences window which allows editing of the layer groups.
* gtk GetXY Action:: N_("Get a coordinate.");
* gtk ImportGUI Action:: N_("Asks user which schematics to import into PCB.
");
* gtk Pan Action:: N_("Start or stop panning (Mode = 1 to start, 0 to stop)
Optional thumb argument is ignored for now in gtk hid.
");
* gtk Popup Action:: N_("Bring up the popup menu specified by @code{MenuName}.
If called by a mouse event then the mouse button number
must be specified as the optional second argument.");
* gtk Print Action:: N_("Print the layout.");
* gtk PrintCalibrate Action:: N_("Calibrate the printer.");
* gtk Save Action:: N_("Save layout and/or element data to a user-selected file.");
* gtk SelectLayer Action:: Select which layer is the current layer.
* gtk SetUnits Action:: N_("Set the default measurement units.");
* gtk SwapSides Action:: N_("Swaps the side of the board you're looking at.");
* gtk ToggleView Action:: Toggle the visibility of the specified layer or layer group.
* gtk Zoom Action:: N_("Various zoom factor changes.");
@end menu
@node gtk About Action
@subsection gtk About
@c key gtk About in hid gtk
@cartouche
@format
About()@end format
@end cartouche

N_("Tell the user about this version of PCB.");
@c ./../src/hid/gtk/gtkhid-main.c 1059

This just pops up a dialog telling the user which version of
@code{pcb} they're running.


@node gtk AdjustStyle Action
@subsection gtk AdjustStyle
@c key gtk AdjustStyle in hid gtk
@cartouche
@format
AdjustStyle()
@end format
@end cartouche

Open the window which allows editing of the route styles.
@c ./../src/hid/gtk/gui-top-window.c 2081

Opens the window which allows editing of the route styles.


@node gtk Center Action
@subsection gtk Center
@c key gtk Center in hid gtk
@cartouche
@format
Center()
@end format
@end cartouche

N_("Moves the pointer to the center of the window.");
@c ./../src/hid/gtk/gtkhid-main.c 1470

Move the pointer to the center of the window, but only if it's
currently within the window already.


@node gtk Cursor Action
@subsection gtk Cursor
@c key gtk Cursor in hid gtk
@cartouche
@format
Cursor(Type,DeltaUp,DeltaRight,Units)@end format
@end cartouche

N_("Move the cursor.");
@c ./../src/hid/gtk/gtkhid-main.c 1515

This action moves the mouse cursor.  Unlike other actions which take
coordinates, this action's coordinates are always relative to the
user's view of the board.  Thus, a positive @var{DeltaUp} may move the
cursor towards the board origin if the board is inverted.

Type is one of @samp{Pan} or @samp{Warp}.  @samp{Pan} causes the
viewport to move such that the crosshair is under the mouse cursor.
@samp{Warp} causes the mouse cursor to move to be above the crosshair.

@var{Units} can be one of the following:

@table @samp

@item mil
@itemx mm
The cursor is moved by that amount, in board units.

@item grid
The cursor is moved by that many grid points.

@item view
The values are percentages of the viewport's view.  Thus, a pan of
@samp{100} would scroll the viewport by exactly the width of the
current view.

@item board
The values are percentages of the board size.  Thus, a move of
@samp{50,50} moves you halfway across the board.

@end table


@node gtk DoWindows Action
@subsection gtk DoWindows
@c key gtk DoWindows in hid gtk
@cartouche
@format
DoWindows(1|2|3|4|5|6)
DoWindows(Layout|Library|Log|Netlist|Preferences|DRC)@end format
@end cartouche

N_("Open various GUI windows.");
@c ./../src/hid/gtk/gtkhid-main.c 1563

@table @code

@item 1
@itemx Layout
Open the layout window.  Since the layout window is always shown
anyway, this has no effect.

@item 2
@itemx Library
Open the library window.

@item 3
@itemx Log
Open the log window.

@item 4
@itemx Netlist
Open the netlist window.

@item 5
@itemx Preferences
Open the preferences window.

@item 6
@itemx DRC
Open the DRC violations window.

@end table


@node gtk EditLayerGroups Action
@subsection gtk EditLayerGroups
@c key gtk EditLayerGroups in hid gtk
@cartouche
@format
EditLayerGroups()
@end format
@end cartouche

Open the preferences window which allows editing of the layer groups.
@c ./../src/hid/gtk/gui-top-window.c 2100

Opens the preferences window which is where the layer groups
are edited.  This action is primarily provides to provide menu
resource compatibility with the lesstif HID.


@node gtk GetXY Action
@subsection gtk GetXY
@c key gtk GetXY in hid gtk
@cartouche
@format
GetXY()@end format
@end cartouche

N_("Get a coordinate.");
@c ./../src/hid/gtk/gtkhid-main.c 1074

Prompts the user for a coordinate, if one is not already selected.


@node gtk ImportGUI Action
@subsection gtk ImportGUI
@c key gtk ImportGUI in hid gtk
@cartouche
@format
ImportGUI()@end format
@end cartouche

N_("Asks user which schematics to import into PCB.
");
@c ./../src/hid/gtk/gtkhid-main.c 1750

Asks user which schematics to import into PCB.


@node gtk Pan Action
@subsection gtk Pan
@c key gtk Pan in hid gtk
@cartouche
@format
Pan([thumb], Mode)@end format
@end cartouche

N_("Start or stop panning (Mode = 1 to start, 0 to stop)
Optional thumb argument is ignored for now in gtk hid.
");
@c ./../src/hid/gtk/gtkhid-main.c 1687

Start or stop panning.  To start call with Mode = 1, to stop call with
Mode = 0.


@node gtk Popup Action
@subsection gtk Popup
@c key gtk Popup in hid gtk
@cartouche
@format
Popup(MenuName, [Button])@end format
@end cartouche

N_("Bring up the popup menu specified by @code{MenuName}.
If called by a mouse event then the mouse button number
must be specified as the optional second argument.");
@c ./../src/hid/gtk/gtkhid-main.c 1719

This just pops up the specified menu.  The menu must have been defined
as a named subresource of the Popups resource in the menu resource
file.


@node gtk Print Action
@subsection gtk Print
@c key gtk Print in hid gtk
@cartouche
@format
Print()@end format
@end cartouche

N_("Print the layout.");
@c ./../src/hid/gtk/gtkhid-main.c 1350

This will find the default printing HID, prompt the user for its
options, and print the layout.


@node gtk PrintCalibrate Action
@subsection gtk PrintCalibrate
@c key gtk PrintCalibrate in hid gtk
@cartouche
@format
PrintCalibrate()@end format
@end cartouche

N_("Calibrate the printer.");
@c ./../src/hid/gtk/gtkhid-main.c 1401

This will print a calibration page, which you would measure and type
the measurements in, so that future printouts will be more precise.


@node gtk Save Action
@subsection gtk Save
@c key gtk Save in hid gtk
@cartouche
@format
Save()
Save(Layout|LayoutAs)
Save(AllConnections|AllUnusedPins|ElementConnections)
Save(PasteBuffer)@end format
@end cartouche

N_("Save layout and/or element data to a user-selected file.");
@c ./../src/hid/gtk/gtkhid-main.c 1230

This action is a GUI front-end to the core's @code{SaveTo} action
(@pxref{SaveTo Action}).  If you happen to pass a filename, like
@code{SaveTo}, then @code{SaveTo} is called directly.  Else, the
user is prompted for a filename to save, and then @code{SaveTo} is
called with that filename.


@node gtk SelectLayer Action
@subsection gtk SelectLayer
@c key gtk SelectLayer in hid gtk
@cartouche
@format
SelectLayer(1..MAXLAYER|Silk|Rats)@end format
@end cartouche

Select which layer is the current layer.
@c ./../src/hid/gtk/gui-top-window.c 1851

The specified layer becomes the currently active layer.  It is made
visible if it is not already visible


@node gtk SetUnits Action
@subsection gtk SetUnits
@c key gtk SetUnits in hid gtk
@cartouche
@format
SetUnits(mm|mil)@end format
@end cartouche

N_("Set the default measurement units.");
@c ./../src/hid/gtk/gtkhid-main.c 1606

@table @code

@item mil
Sets the display units to mils (1/1000 inch).

@item mm
Sets the display units to millimeters.

@end table


@node gtk SwapSides Action
@subsection gtk SwapSides
@c key gtk SwapSides in hid gtk
@cartouche
@format
SwapSides(|v|h|r)@end format
@end cartouche

N_("Swaps the side of the board you're looking at.");
@c ./../src/hid/gtk/gtkhid-main.c 1295

This action changes the way you view the board.

@table @code

@item v
Flips the board over vertically (up/down).

@item h
Flips the board over horizontally (left/right), like flipping pages in
a book.

@item r
Rotates the board 180 degrees without changing sides.

@end table

If no argument is given, the board isn't moved but the opposite side
is shown.

Normally, this action changes which pads and silk layer are drawn as
true silk, and which are drawn as the "invisible" layer.  It also
determines which solder mask you see.

As a special case, if the layer group for the side you're looking at
is visible and currently active, and the layer group for the opposite
is not visible (i.e. disabled), then this action will also swap which
layer group is visible and active, effectively swapping the ``working
side'' of the board.


@node gtk ToggleView Action
@subsection gtk ToggleView
@c key gtk ToggleView in hid gtk
@cartouche
@format
ToggleView(1..MAXLAYER)
ToggleView(layername)
ToggleView(Silk|Rats|Pins|Vias|Mask|BackSide)@end format
@end cartouche

Toggle the visibility of the specified layer or layer group.
@c ./../src/hid/gtk/gui-top-window.c 1792

If you pass an integer, that layer is specified by index (the first
layer is @code{1}, etc).  If you pass a layer name, that layer is
specified by name.  When a layer is specified, the visibility of the
layer group containing that layer is toggled.

If you pass a special layer name, the visibility of those components
(silk, rats, etc) is toggled.  Note that if you have a layer named
the same as a special layer, the layer is chosen over the special layer.


@node gtk Zoom Action
@subsection gtk Zoom
@c key gtk Zoom in hid gtk
@cartouche
@format
Zoom()
Zoom(factor)@end format
@end cartouche

N_("Various zoom factor changes.");
@c ./../src/hid/gtk/gtkhid-main.c 161
Changes the zoom (magnification) of the view of the board.  If no
arguments are passed, the view is scaled such that the board just fits
inside the visible window (i.e. ``view all'').  Otherwise,
@var{factor} specifies a change in zoom factor.  It may be prefixed by
@code{+}, @code{-}, or @code{=} to change how the zoom factor is
modified.  The @var{factor} is a floating point number, such as
@code{1.5} or @code{0.75}.

@table @code
  
@item +@var{factor}
Values greater than 1.0 cause the board to be drawn smaller; more of
the board will be visible.  Values between 0.0 and 1.0 cause the board
to be drawn bigger; less of the board will be visible.
  
@item -@var{factor}
Values greater than 1.0 cause the board to be drawn bigger; less of
the board will be visible.  Values between 0.0 and 1.0 cause the board
to be drawn smaller; more of the board will be visible.
 
@item =@var{factor}
 
The @var{factor} is an absolute zoom factor; the unit for this value
is "PCB units per screen pixel".  Since PCB units are 0.01 mil, a
@var{factor} of 1000 means 10 mils (0.01 in) per pixel, or 100 DPI,
about the actual resolution of most screens - resulting in an "actual
size" board.  Similarly, a @var{factor} of 100 gives you a 10x actual
size.
 
@end table
 
Note that zoom factors of zero are silently ignored.
 



@node lesstif actions
@section lesstif actions
@menu
* lesstif About Action:: Tell the user about this version of PCB.
* lesstif AdjustSizes Action:: Let the user change the board size, DRC parameters, etc
* lesstif AdjustStyle Action:: Displays the route style adjustment window.
* lesstif Benchmark Action:: Benchmark the GUI speed.
* lesstif Command Action:: Displays the command line input window.
* lesstif Cursor Action:: Move the cursor.
* lesstif Debug Action:: Debug action.
* lesstif DebugXY Action:: Debug action, with coordinates
* lesstif DoWindows Action:: Open various GUI windows.
* lesstif DumpKeys Action:: Dump Lesstif key bindings.
* lesstif EditLayerGroups Action:: Let the user change the layer groupings
* lesstif Export Action:: Export the layout.
* lesstif GetXY Action:: Get a coordinate.
* lesstif ImportGUI Action:: Lets the user choose the schematics to import from
* lesstif LibraryShow Action:: Displays the library window.
* lesstif Load Action:: Load layout data from a user-selected file.
* lesstif LoadVendor Action:: Loads a user-selected vendor resource file.
* lesstif NetlistShow Action:: Selects the given pinname or netname in the netlist window.
* lesstif Print Action:: Print the layout.
* lesstif PrintCalibrate Action:: Calibrate the printer.
* lesstif PromptFor Action:: Prompt for a response.
* lesstif Return Action:: Simulate a passing or failing action.
* lesstif Save Action:: Save layout data to a user-selected file.
* lesstif SelectLayer Action:: Select which layer is the current layer.
* lesstif SetUnits Action:: Set the default measurement units.
* lesstif SwapSides Action:: Swaps the side of the board you're looking at.
* lesstif ToggleView Action:: Toggle the visibility of the specified layer or layer group.
* lesstif Zoom Action:: Various zoom factor changes.
@end menu
@node lesstif About Action
@subsection lesstif About
@c key lesstif About in hid lesstif
@cartouche
@format
About()@end format
@end cartouche

Tell the user about this version of PCB.
@c ./../src/hid/lesstif/dialogs.c 867

This just pops up a dialog telling the user which version of
@code{pcb} they're running.


@node lesstif AdjustSizes Action
@subsection lesstif AdjustSizes
@c key lesstif AdjustSizes in hid lesstif
@cartouche
@format
AdjustSizes()@end format
@end cartouche

Let the user change the board size, DRC parameters, etc
@c ./../src/hid/lesstif/dialogs.c 1136

Displays a dialog box that lets the user change the board
size, DRC parameters, and text scale.

The units are determined by the default display units.


@node lesstif AdjustStyle Action
@subsection lesstif AdjustStyle
@c key lesstif AdjustStyle in hid lesstif
@cartouche
@format
AdjustStyle()@end format
@end cartouche

Displays the route style adjustment window.
@c ./../src/hid/lesstif/styles.c 344


@node lesstif Benchmark Action
@subsection lesstif Benchmark
@c key lesstif Benchmark in hid lesstif
@cartouche
@format
Benchmark()@end format
@end cartouche

Benchmark the GUI speed.
@c ./../src/hid/lesstif/main.c 659

This action is used to speed-test the Lesstif graphics subsystem.  It
redraws the current screen as many times as possible in ten seconds.
It reports the amount of time needed to draw the screen once.


@node lesstif Command Action
@subsection lesstif Command
@c key lesstif Command in hid lesstif
@cartouche
@format
Command()@end format
@end cartouche

Displays the command line input window.
@c ./../src/hid/lesstif/main.c 644

The command window allows the user to manually enter actions to be
executed.  Action syntax can be done one of two ways:

@table @code

@item
Follow the action name by an open parenthesis, arguments separated by
commas, end with a close parenthesis.  Example: @code{Abc(1,2,3)}

@item
Separate the action name and arguments by spaces.  Example: @code{Abc
1 2 3}.

@end table

The first option allows you to have arguments with spaces in them,
but the second is more ``natural'' to type for most people.

Note that action names are not case sensitive, but arguments normally
are.  However, most actions will check for ``keywords'' in a case
insensitive way.

There are three ways to finish with the command window.  If you press
the @code{Enter} key, the command is invoked, the window goes away,
and the next time you bring up the command window it's empty.  If you
press the @code{Esc} key, the window goes away without invoking
anything, and the next time you bring up the command window it's
empty.  If you change focus away from the command window (i.e. click
on some other window), the command window goes away but the next time
you bring it up it resumes entering the command you were entering
before.


@node lesstif Cursor Action
@subsection lesstif Cursor
@c key lesstif Cursor in hid lesstif
@cartouche
@format
Cursor(Type,DeltaUp,DeltaRight,Units)@end format
@end cartouche

Move the cursor.
@c ./../src/hid/lesstif/main.c 716

This action moves the mouse cursor.  Unlike other actions which take
coordinates, this action's coordinates are always relative to the
user's view of the board.  Thus, a positive @var{DeltaUp} may move the
cursor towards the board origin if the board is inverted.

Type is one of @samp{Pan} or @samp{Warp}.  @samp{Pan} causes the
viewport to move such that the crosshair is under the mouse cursor.
@samp{Warp} causes the mouse cursor to move to be above the crosshair.

@var{Units} can be one of the following:

@table @samp

@item mil
@itemx mm
The cursor is moved by that amount, in board units.

@item grid
The cursor is moved by that many grid points.

@item view
The values are percentages of the viewport's view.  Thus, a pan of
@samp{100} would scroll the viewport by exactly the width of the
current view.

@item board
The values are percentages of the board size.  Thus, a move of
@samp{50,50} moves you halfway across the board.

@end table


@node lesstif Debug Action
@subsection lesstif Debug
@c key lesstif Debug in hid lesstif
@cartouche
@format
Debug(...)@end format
@end cartouche

Debug action.
@c ./../src/hid/lesstif/menu.c 66

This action exists to help debug scripts; it simply prints all its
arguments to stdout.


@node lesstif DebugXY Action
@subsection lesstif DebugXY
@c key lesstif DebugXY in hid lesstif
@cartouche
@format
DebugXY(...)@end format
@end cartouche

Debug action, with coordinates
@c ./../src/hid/lesstif/menu.c 72

Like @code{Debug}, but requires a coordinate.  If the user hasn't yet
indicated a location on the board, the user will be prompted to click
on one.


@node lesstif DoWindows Action
@subsection lesstif DoWindows
@c key lesstif DoWindows in hid lesstif
@cartouche
@format
DoWindows(1|2|3|4)
DoWindows(Layout|Library|Log|Netlist)@end format
@end cartouche

Open various GUI windows.
@c ./../src/hid/lesstif/dialogs.c 831

@table @code

@item 1
@itemx Layout
Open the layout window.  Since the layout window is always shown
anyway, this has no effect.

@item 2
@itemx Library
Open the library window.

@item 3
@itemx Log
Open the log window.

@item 4
@itemx Netlist
Open the netlist window.

@end table


@node lesstif DumpKeys Action
@subsection lesstif DumpKeys
@c key lesstif DumpKeys in hid lesstif
@cartouche
@format
DumpKeys()@end format
@end cartouche

Dump Lesstif key bindings.
@c ./../src/hid/lesstif/menu.c 101

Causes the list of key bindings (from @code{pcb-menu.res}) to be
dumped to stdout.  This is most useful when invoked from the command
line like this:

@example
pcb --action-string DumpKeys
@end example


@node lesstif EditLayerGroups Action
@subsection lesstif EditLayerGroups
@c key lesstif EditLayerGroups in hid lesstif
@cartouche
@format
EditLayerGroups()@end format
@end cartouche

Let the user change the layer groupings
@c ./../src/hid/lesstif/dialogs.c 1448

Displays a dialog that lets the user view and change the layer
groupings.  Each layer (row) can be a member of any one layer group
(column).  Note the special layers @code{solder} and @code{component}
allow you to specify which groups represent the top and bottom of the
board.

See @ref{ChangeName Action}.


@node lesstif Export Action
@subsection lesstif Export
@c key lesstif Export in hid lesstif
@cartouche
@format
Export()@end format
@end cartouche

Export the layout.
@c ./../src/hid/lesstif/dialogs.c 957

Prompts the user for an exporter to use.  Then, prompts the user for
that exporter's options, and exports the layout.


@node lesstif GetXY Action
@subsection lesstif GetXY
@c key lesstif GetXY in hid lesstif
@cartouche
@format
GetXY()@end format
@end cartouche

Get a coordinate.
@c ./../src/hid/lesstif/menu.c 54

Prompts the user for a coordinate, if one is not already selected.


@node lesstif ImportGUI Action
@subsection lesstif ImportGUI
@c key lesstif ImportGUI in hid lesstif
@cartouche
@format
ImportGUI()@end format
@end cartouche

Lets the user choose the schematics to import from
@c ./../src/hid/lesstif/dialogs.c 1882

Displays a dialog that lets the user select the schematic(s) to import
from, then saves that information in the layout's attributes for
future imports.


@node lesstif LibraryShow Action
@subsection lesstif LibraryShow
@c key lesstif LibraryShow in hid lesstif
@cartouche
@format
LibraryShow()@end format
@end cartouche

Displays the library window.
@c ./../src/hid/lesstif/library.c 151


@node lesstif Load Action
@subsection lesstif Load
@c key lesstif Load in hid lesstif
@cartouche
@format
Load()
Load(Layout|LayoutToBuffer|ElementToBuffer|Netlist|Revert)@end format
@end cartouche

Load layout data from a user-selected file.
@c ./../src/hid/lesstif/dialogs.c 99

This action is a GUI front-end to the core's @code{LoadFrom} action
(@pxref{LoadFrom Action}).  If you happen to pass a filename, like
@code{LoadFrom}, then @code{LoadFrom} is called directly.  Else, the
user is prompted for a filename to load, and then @code{LoadFrom} is
called with that filename.


@node lesstif LoadVendor Action
@subsection lesstif LoadVendor
@c key lesstif LoadVendor in hid lesstif
@cartouche
@format
LoadVendor()@end format
@end cartouche

Loads a user-selected vendor resource file.
@c ./../src/hid/lesstif/dialogs.c 152

The user is prompted for a file to load, and then
@code{LoadVendorFrom} is called (@pxref{LoadVendorFrom Action}) to
load that vendor file.


@node lesstif NetlistShow Action
@subsection lesstif NetlistShow
@c key lesstif NetlistShow in hid lesstif
@cartouche
@format
NetlistShow(pinname|netname)@end format
@end cartouche

Selects the given pinname or netname in the netlist window.
@c ./../src/hid/lesstif/netlist.c 415


@node lesstif Print Action
@subsection lesstif Print
@c key lesstif Print in hid lesstif
@cartouche
@format
Print()@end format
@end cartouche

Print the layout.
@c ./../src/hid/lesstif/dialogs.c 894

This will find the default printing HID, prompt the user for its
options, and print the layout.


@node lesstif PrintCalibrate Action
@subsection lesstif PrintCalibrate
@c key lesstif PrintCalibrate in hid lesstif
@cartouche
@format
PrintCalibrate()@end format
@end cartouche

Calibrate the printer.
@c ./../src/hid/lesstif/dialogs.c 937

This will print a calibration page, which you would measure and type
the measurements in, so that future printouts will be more precise.


@node lesstif PromptFor Action
@subsection lesstif PromptFor
@c key lesstif PromptFor in hid lesstif
@cartouche
@format
PromptFor([message[,default]])@end format
@end cartouche

Prompt for a response.
@c ./../src/hid/lesstif/dialogs.c 560

This is mostly for testing the lesstif HID interface.  The parameters
are passed to the @code{prompt_for()} HID function, causing the user
to be prompted for a response.  The respose is simply printed to the
user's stdout.


@node lesstif Return Action
@subsection lesstif Return
@c key lesstif Return in hid lesstif
@cartouche
@format
Return(0|1)@end format
@end cartouche

Simulate a passing or failing action.
@c ./../src/hid/lesstif/menu.c 89

This is for testing.  If passed a 0, does nothing and succeeds.  If
passed a 1, does nothing but pretends to fail.


@node lesstif Save Action
@subsection lesstif Save
@c key lesstif Save in hid lesstif
@cartouche
@format
Save()
Save(Layout|LayoutAs)
Save(AllConnections|AllUnusedPins|ElementConnections)
Save(PasteBuffer)@end format
@end cartouche

Save layout data to a user-selected file.
@c ./../src/hid/lesstif/dialogs.c 197

This action is a GUI front-end to the core's @code{SaveTo} action
(@pxref{SaveTo Action}).  If you happen to pass a filename, like
@code{SaveTo}, then @code{SaveTo} is called directly.  Else, the
user is prompted for a filename to save, and then @code{SaveTo} is
called with that filename.


@node lesstif SelectLayer Action
@subsection lesstif SelectLayer
@c key lesstif SelectLayer in hid lesstif
@cartouche
@format
SelectLayer(1..MAXLAYER|Silk|Rats)@end format
@end cartouche

Select which layer is the current layer.
@c ./../src/hid/lesstif/menu.c 387

The specified layer becomes the currently active layer.  It is made
visible if it is not already visible


@node lesstif SetUnits Action
@subsection lesstif SetUnits
@c key lesstif SetUnits in hid lesstif
@cartouche
@format
SetUnits(mm|mil)@end format
@end cartouche

Set the default measurement units.
@c ./../src/hid/lesstif/main.c 395

@table @code

@item mil
Sets the display units to mils (1/1000 inch).

@item mm
Sets the display units to millimeters.

@end table


@node lesstif SwapSides Action
@subsection lesstif SwapSides
@c key lesstif SwapSides in hid lesstif
@cartouche
@format
SwapSides(|v|h|r)@end format
@end cartouche

Swaps the side of the board you're looking at.
@c ./../src/hid/lesstif/main.c 494

This action changes the way you view the board.

@table @code

@item v
Flips the board over vertically (up/down).

@item h
Flips the board over horizontally (left/right), like flipping pages in
a book.

@item r
Rotates the board 180 degrees without changing sides.

@end table

If no argument is given, the board isn't moved but the opposite side
is shown.

Normally, this action changes which pads and silk layer are drawn as
true silk, and which are drawn as the "invisible" layer.  It also
determines which solder mask you see.

As a special case, if the layer group for the side you're looking at
is visible and currently active, and the layer group for the opposite
is not visible (i.e. disabled), then this action will also swap which
layer group is visible and active, effectively swapping the ``working
side'' of the board.


@node lesstif ToggleView Action
@subsection lesstif ToggleView
@c key lesstif ToggleView in hid lesstif
@cartouche
@format
ToggleView(1..MAXLAYER)
ToggleView(layername)
ToggleView(Silk|Rats|Pins|Vias|Mask|BackSide)@end format
@end cartouche

Toggle the visibility of the specified layer or layer group.
@c ./../src/hid/lesstif/menu.c 409

If you pass an integer, that layer is specified by index (the first
layer is @code{1}, etc).  If you pass a layer name, that layer is
specified by name.  When a layer is specified, the visibility of the
layer group containing that layer is toggled.

If you pass a special layer name, the visibility of those components
(silk, rats, etc) is toggled.  Note that if you have a layer named
the same as a special layer, the layer is chosen over the special layer.


@node lesstif Zoom Action
@subsection lesstif Zoom
@c key lesstif Zoom in hid lesstif
@cartouche
@format
Zoom()
Zoom(factor)@end format
@end cartouche

Various zoom factor changes.
@c ./../src/hid/lesstif/main.c 419

Changes the zoom (magnification) of the view of the board.  If no
arguments are passed, the view is scaled such that the board just fits
inside the visible window (i.e. ``view all'').  Otherwise,
@var{factor} specifies a change in zoom factor.  It may be prefixed by
@code{+}, @code{-}, or @code{=} to change how the zoom factor is
modified.  The @var{factor} is a floating point number, such as
@code{1.5} or @code{0.75}.

@table @code

@item +@var{factor}
Values greater than 1.0 cause the board to be drawn smaller; more of
the board will be visible.  Values between 0.0 and 1.0 cause the board
to be drawn bigger; less of the board will be visible.

@item -@var{factor}
Values greater than 1.0 cause the board to be drawn bigger; less of
the board will be visible.  Values between 0.0 and 1.0 cause the board
to be drawn smaller; more of the board will be visible.

@item =@var{factor}

The @var{factor} is an absolute zoom factor; the unit for this value
is "PCB units per screen pixel".  Since PCB units are 0.01 mil, a
@var{factor} of 1000 means 10 mils (0.01 in) per pixel, or 100 DPI,
about the actual resolution of most screens - resulting in an "actual
size" board.  Similarly, a @var{factor} of 100 gives you a 10x actual
size.

@end table

Note that zoom factors of zero are silently ignored.


