# pcb-rnd actions (details)

## AddRats

  Syntax summary: | AddRats(AllRats|SelectedRats|Close, [manhattan])
  Help text: | Add one or more rat lines to the board.
  Registered by: | n/a

  First argument:

  AllRats | Create rat lines for all loaded nets that aren't already connected on with copper.
  SelectedRats | Similarly, but only add rat lines for nets connected to selected pins and pads.
  Close | Selects the shortest unselected rat on the board.

  The second argument is temporary and optional, for a workaround of a bug in the old (to be removed) autorouter. If the value of the second argument is "manhattan", non-axis-aligned lines are ignored when looking for rat anchor points.

## AdjustStyle

  Syntax summary: | AdjustStyle([routestyle_idx])
  Help text: | Open the dialog box for editing the route styles.
  Registered by: | lib_hid_pcbui/route_style

  With no argument or negative argument, operate on the currently selected style (if there's any). Else operate on the style indexed.

## align

  Syntax summary: | Align(X/Y, [Lefts/Rights/Tops/Bottoms/Centers/Marks, [First/Last/pcb_crosshair/Average[, Gridless]]])
  Help text: | Align objects
  Registered by: | distalign plugin

  Example: Align(X, [Lefts/Rights/Centers/Marks, [First/Last/pcb_crosshair/Average[, Gridless]]])

  Example: Align(Y, [Tops/Bottoms/Centers/Marks, [First/Last/pcb_crosshair/Average[, Gridless]]])

  Arguments:

  X or Y | Select which axis will move, other is untouched.
  Lefts, Rights, Tops, Bottoms, Centers, Marks | Pick alignment point within each object
  First, Last, pcb_crosshair, Average | Alignment reference, First=Topmost/Leftmost, Last=Bottommost/Rightmost, Average or pcb_crosshair point
  Gridless | Do not force results to align to prevailing grid.

  Defaults are Marks, First.

  For non-subcircuit objects: using Marks is not recommended, using Gridless is recommended.

## ApplyPen

  Syntax summary: | ApplyPen([selected|object])
  Help text: | Set properties of the selected object or object under the cursor to match current drawing style ("pen"), e.g. thickness, clearance.
  Registered by: | n/a

  Changes existing object(s) to look like as if it was (they were) drawn using the current "pen". For example ApplyPen on a line object will change the line thickness and line clearance values to the current line thickness and clearance values a new line is drawn with using the line tool.

  This action is the inverse pair of the setsame action.

## ApplyVendor

  Syntax summary: | ApplyVendor()
  Help text: | Applies the currently loaded vendor drill table to the current design.
  Registered by: | vendor drill mapping

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

## ArcNew

  Syntax summary: | ArcNew([noundo,] data, layer, centx, centy, radiusx, radiusy, start_ang, delta_ang, thickness, clearance, flags)
  Help text: | Create a pcb arc segment on a layer. For now data must be "pcb". Returns the idpath of the new object or 0 on error.
  Registered by: | act_draw

  Creates a new arc object on target layer.

  The first argument is the usual optional "noundo". Then come the mandatory data and layer arguments for addressing the target layer. Coordinates of center and radii follow. Angles are specified in decimal degrees. Finally thickness, clearance coordinates and symbolic flag names passed as a string of comma separated list (can be empty).

## Atomic

  Syntax summary: | Atomic(Save|Restore|Close|Block)
  Help text: | Save or restore the undo serial number.
  Registered by: | n/a

  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 Save , delete the rats, Restore , add the rats - using the same serial number as the deletes, then 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.

  An alternative mechanism is freeze/unfreeze for the case restoring between every two actions is not possible or not practical. The sequence is Save , Freeze , call actions, UnFreeze , Block .

  Arguments:

  Save | Saves the undo serial number.
  Restore | Returns it to the last saved number.
  Close | Sets it to 1 greater than the last save.
  Block | Does a Restore if there was nothing to undo, else does a Close.
  Freeze | Make sure no subsequent actions will bump the undo serial
  UnFreeze or Thaw | Allow subsequent actions to bump the undo serial again

## Attributes

  Syntax summary: | Attributes(Layout|Layer|Element|Subc) Attributes(Layer,layername)
  Help text: | Let the user edit the attributes of the layout, current or given layer, or selected subcircuit.
  Registered by: | oldactions plugin

  Pops up a dialog letting the user edit the attributes of the pcb, a subcircuit, or a layer.

## AutoPlaceSelected

  Syntax summary: | AutoPlaceSelected()
  Help text: | Auto-place selected components.
  Registered by: | autoplace plugin

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

## AutoRoute

  Syntax summary: | AutoRoute(AllRats|SelectedRats)
  Help text: | Auto-route some or all rat lines.
  Registered by: | autoroute plugin

  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 routing 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.

  Arguments:

  AllRats | Attempt to autoroute all rats.
  SelectedRats | Attempt to autoroute the selected rats.

## baconn

  Syntax summary: | BaConn(object|selected, add, [netname]) BaConn(object|selected, remove)
  Help text: | Add a terminal-net connection to the back annotation list or add a terminal-net connection removal to the back annotation list
  Registered by: | n/a

  Put terminal-net related changes to the netlist patch (to be back annotated). The first argument sets scope (e.g. subcircuit under the cursor or all selected subcircuits), the second argument is the actual operation.

  See also: back annotation

## basubc

  Syntax summary: | BaSubc(object|selected, add|remove)
  Help text: | Add new subcircuits to the back annotation list or remove and back annotate removal of a subcircuit
  Registered by: | n/a

  Put subc related changes to the netlist patch (to be back annotated). The first argument sets scope (e.g. subcircuit under the cursor or all selected subcircuits), the second argument is the actual operation.

  See also: back annotation

## BoardFlip

  Syntax summary: | BoardFlip([sides])
  Help text: | Mirror the board over the x axis, optionally mirroring sides as well.
  Registered by: | n/a

  All objects on the board are up-down flipped (mirrored over the x axis).

  Command line board flipping:

       echo " BoardFlip() SaveTo(LayoutAs,$OUTFILE) Quit() " | pcb $INFILE

  To flip the board physically, use BoardFlip(sides)

## ChangeClearSize

  Syntax summary: | ChangeClearSize(Object, delta|style) ChangeClearSize(SelectedPins|SelectedPads|SelectedVias, delta|style) ChangeClearSize(SelectedLines|SelectedArcs, delta|style) ChangeClearSize(Selected|SelectedObjects, delta|style)
  Help text: | Changes the clearance size of objects.
  Registered by: | n/a

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

## ChangeFlag

  Syntax summary: | ChangeFlag(Object|Selected|SelectedObjects, flag, value) ChangeFlag(SelectedLines|SelectedPins|SelectedVias, flag, value) ChangeFlag(SelectedPads|SelectedTexts|SelectedNames, flag, value) ChangeFlag(SelectedElements, flag, value) flag = join value = 0 | 1
  Help text: | Sets or clears flags on objects.
  Registered by: | n/a

  Toggles the given flag on the indicated object(s). The flag may be one of the flags listed above (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.

## ChangeJoin

  Syntax summary: | ChangeJoin(ToggleObject|SelectedLines|SelectedArcs|Selected)
  Help text: | Changes the join (clearance through polygons) of objects.
  Registered by: | n/a

  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.

## ChangeName

  Syntax summary: | ChangeName(Object) ChangeName(Refdes) ChangeName(Layout|Layer)
  Help text: | Sets the name, text string, terminal ID or refdes of objects.
  Registered by: | n/a

  Arguments:

  Object | Changes the "name" of the object under the cursor. For a text object this is the text string. For a terminal, this is the terminal ID. For a subcircuit this is the refdes. For a subc text object that has only the refdes template in it, it offers changing the text object (template) or the parent subcircuit's refdes attribute.
  Refdes | Changes the refdes attribute of a subcircuit under the cursor.
  Layout | Changes the name of the layout. This is printed on the fab drawings.
  Layer | Changes the name of the currently active layer.

## ChangePinName

  Syntax summary: | ChangePinName(Refdes,PinNumber,PinName)
  Help text: | Sets the name of a specific pin on a specific subcircuit.
  Registered by: | n/a

  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)

## ChangeSize

  Syntax summary: | ChangeSize(Object, delta|style) ChangeSize(SelectedObjects|Selected, delta|style) ChangeSize(SelectedLines|SelectedPins|SelectedVias, delta|style) ChangeSize(SelectedPads|SelectedTexts|SelectedNames, delta|style) ChangeSize(SelectedElements, delta|style)
  Help text: | Changes the size of objects.
  Registered by: | n/a

  For lines and arcs, this changes the width. For padstacks, this changes the shape size (but does not touch the hole diameter). For texts, this changes the scaling factor. For subcircuits, this changes the width of the lines and arcs and shape sizes of padstacks (thus mostly relative values make sense).

## ChangeSizes

  Syntax summary: | ChangeSizes(Object, delta|style) ChangeSizes(SelectedObjects|Selected, delta|style) ChangeSizes(SelectedLines|SelectedPins|SelectedVias, delta|style) ChangeSizes(SelectedPads|SelectedTexts|SelectedNames, delta|style) ChangeSizes(SelectedElements, delta|style)
  Help text: | Changes all sizes of objects.
  Registered by: | n/a

  Call ChangeSize, ChangeDrillSize and ChangeClearSize with the same arguments. If any of them did not fail, return success.

## ChkLayer

  Syntax summary: | ChkLayer(layerid)
  Help text: | Returns 1 if the specified layer is the active layer
  Registered by: | n/a

  Returns 1 if the specified layer is the active layer.

## ChkRst

  Syntax summary: | ChkRst(route_style_id)
  Help text: | Return 1 if route_style_id matches pen.
  Registered by: | n/a

  Return 1 if route_style_id matches pen.

## ChkView

  Syntax summary: | ChkView(layerid)
  Help text: | Return 1 if layerid is visible.
  Registered by: | n/a

  Return 1 if layerid is visible. Intended for menu item 'checked' fields.

## claimnet

  Syntax summary: | ClaimNet(object|selected|found,[netname])
  Help text: | Claim existing connections and create a new net
  Registered by: | n/a

  The ClaimNet() action can be used to construct network metadata (netlist entry) converting existing physical (galvanic, copper) connections or object lists.

  When galvanic connections are mapped, the first argument shall be object ; in this case the object under the mouse cursor is the starting point and anything galvanically connected (at the moment) is considered part of the new network. This mode of operation is useful for capturing existing nets.

  When the first argument is selected or found , the list of (selected or found) terminals are converted to a new net, regardless of galvanic connections. This mode is useful for designing a PCB by a netlist but without a schematics - in this setup the netlist is "drawn" in pcb-rnd as well.

  If netname is specified, the user is prompted for a name.

## ClrFlag

  Syntax summary: | ClrFlag(Object|Selected|SelectedObjects, flag) ClrFlag(SelectedLines|SelectedPins|SelectedVias, flag) ClrFlag(SelectedPads|SelectedTexts|SelectedNames, flag) ClrFlag(SelectedElements, flag) flag = thermal | join
  Help text: | Clears flags on objects.
  Registered by: | n/a

  Turns the given flag off, regardless of its previous setting. See changeflag .

  Example: ClrFlag(SelectedLines,join)

## Command

  Syntax summary: | Command()
  Help text: | Displays the command line input in the status area.
  Registered by: | lib_hid_common plugin

  The command entry allows the user to manually enter actions to be executed. This action opens the command entry.

  There are two ways to finish with the command window. If you press the Enter key, the command is invoked, the entry normally goes away, and the next time you bring up the command window it's empty. If you press the Esc key, the window goes away without invoking anything, and the next time you bring up the command window it's empty.

  Use the up and down arrow keys to access command history.

## Connection

  Syntax summary: | Connection(Find|ResetLinesAndPolygons|ResetPinsAndVias|Reset)
  Help text: | Searches connections of the object at the cursor position.
  Registered by: | n/a

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

  Arguments:

  Find | The net under the cursor is "found".
  ResetLayerObjects | Any "found" layer objects (lines, arcs, polygons and texts) are marked "not found".
  ResetPadstacks | Any "found" padstack are marked "not found". WARNING: does not touch non-padstack heavy terminals!
  Reset | All "found" objects are marked "not found".
  ResetLinesAndPolygons | Obsolate, misleading name for ResetLayerObjects. Do not use.
  ResetPinsAndVias | Obsolate, misleading name for ResetPadstacks. Do not use.

## CycleDrag

  Syntax summary: | CycleDrag()
  Help text: | Cycle through which object is being dragged
  Registered by: | n/a

  When multiple overlapping objects are accessible by clicking on a pixel on the screen, drag&drop operations may become harder to do: pcb-rnd will often "pick the wrong object" on click.

  Cycledraw provides a way to get pcb-rnd to jump to selecting another object of the avaialble ones on the original site, while the user is still in drag mode. This obviously works only through the key binding, as selecting the menu would require the drag operation to finish first.

## DisperseElements

  Syntax summary: | DisperseElements(All|Selected|Buffer)
  Help text: | Disperses subcircuits.
  Registered by: | n/a

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

  When the first argument is "buffer", rearrange subcircuits within the buffer so they form a tightly packed rectange centered at the buffer origin. This is useful after the initial import schematics: from sch-rnd cross-select a bunch of subcircuits making up a functional block of the design (e.g. a PSU section), cut to buffer, DisperseElements(buffer) then paste at a spot of the empty board.

## Display

  Syntax summary:

  Display(SubcID, template) Display(Grid|Redraw|Pinout|PinOrPadName) Display(CycleClip|ToggleAllDirections|ToggleStartDirection) Display(RealignGrid|ToggleRubberBandMode|ToggleUniqueNames) Display(ToggleName|ToggleClearLine|ToggleFullPoly|ToggleSnapPin) Display(ToggleSnapOffGridLine|ToggleHighlightOnPoint|ToggleCheckPlanes) Display(ToggleThindraw|ToggleThindrawPoly|ToggleOrthoMove|ToggleLocalRef) Display(ToggleLiveRoute|ToggleShowDRC|ToggleAutoDRC|LockNames|OnlyNames)

  Help text: | Several display-related actions.
  Registered by: | n/a

  Changes random display related global states.

  SubcID Description Value | Specify the subcircuit ID template to be printed on the subcircuit layer
  Redraw | Redraw the whole board.
  ToggleAllDirections | 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.
  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.
  CycleCrosshair | Changes crosshair drawing. Crosshair may accept form of 4-ray, 8-ray and 12-ray cross.
  ToggleRubberBandMode | If set, moving an object moves all the lines attached to it too.
  ToggleStartDirection | If set, each time you set a point in a line, the Clip toggles between orth-angle and angle-ortho.
  ToggleUniqueNames | If set, you will not be permitted to change the name of an element to match that of another element.
  ToggleSnapPin | If set, pin centers and pad end points are treated as additional grid points that the cursor can snap to.
  ToggleSnapOffGridLine | If set, snap at some sensible point along a line.
  ToggleHighlightOnPoint | If set, highlights lines and arcs when the crosshair is on one of their two (end) points.
  ToggleLocalRef | If set, the mark is automatically set to the beginning of any move, so you can see the relative distance you've moved.
  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.
  ToggleThindrawPoly | If set, polygons on the screen are drawn as outlines.
  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.
  ToggleLiveRoute | If set, the progress of the autorouter will be visible on the screen.
  ToggleAutoDRC | If set, you will not be permitted to make connections which violate the current DRC and netlist settings.
  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.
  ToggleOrthoMove | If set, the crosshair is only allowed to move orthogonally from its previous position. I.e. you can move a subcircuit or line up, down, left, or right, but not up+left or down+right.
  ToggleName | Selects whether the pinouts show the pin names or the pin numbers.
  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.
  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.
  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.
  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.
  ToggleGrid | Resets the origin of the current grid to be wherever the crosshair is. If you provide two numbers after this, the origin is set to that coordinate.
  Grid | Toggles whether the grid is displayed or not.
  Pinout | Causes the pinout of the subcircuit indicated by the cursor to be displayed, usually in a separate window.
  PinOrPadName | Toggles whether the names of terminals will be displayed. If the cursor is over an subcircuit, all of its terminals are affected.

## distribute

  Syntax summary: | Distribute(X/Y, [Lefts/Rights/Tops/Bottoms/Centers/Marks/Gaps, [First/Last/pcb_crosshair, First/Last/pcb_crosshair[, Gridless]]])
  Help text: | Distribute objects
  Registered by: | distalign plugin

  Example: Distribute(X, [Lefts/Rights/Centers/Marks/Gaps, [First/Last/pcb_crosshair, First/Last/pcb_crosshair[, Gridless]]])

  Example: Distribute(Y, [Tops/Bottoms/Centers/Marks/Gaps, [First/Last/pcb_crosshair, First/Last/pcb_crosshair[, Gridless]]])

  As with align , plus:

  Arguments:

  Gaps | Make gaps even rather than spreading points evenly.
  First, Last, pcb_crosshair | Two arguments specifying both ends of the distribution, they can't both be the same.

  Defaults are Marks, First, Last

  Distributed objects always retain the same relative order they had before they were distributed.

  For non-subcircuit objects: using Marks is not recommended, using Gridless is recommended.

## djopt

  Syntax summary: | djopt(debumpify|unjaggy|simple|vianudge|viatrim|orthopull) djopt(auto) - all of the above djopt(miter)
  Help text: | Perform various optimizations on the current board.
  Registered by: | djopt

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

  Arguments:

  debumpify | Looks for U-shaped traces that can be shortened or eliminated.
  unjaggy | Looks for corners which could be flipped to eliminate one or more corners (i.e. jaggy lines become simpler).
  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.
  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).
  viatrim | Looks for traces that go from via to via, where moving that trace to a different layer eliminates one or both vias.
  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.
  splitlines | Looks for lines that pass through vias, pins, or pads, and splits them into separate lines so they can be managed separately.
  auto | Performs the above options, repeating until no further optimizations can be made.
  miter | Replaces 90 degree corners with a pair of 45 degree corners, to reduce RF losses and trace length.

## DRC

  Syntax summary: | DRC([list|simple|print|log|dump])
  Help text: | Invoke the DRC check. Results are presented as the argument requests.
  Registered by: | n/a

  Output styles available:

  name | description
  --- | ---
  list | display a full list of all violations, with preview of the current item (large dialog)
  simple | a small & simple dialog that navigates the user through the violations one by one, sequentially
  print | print the list to stdout in human readable form
  log | print the list as INFO lines in the log in human readable form
  dump | print the list to stdout in script readable form

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

## ElementList

  Syntax summary: | ElementList(Start|Done|Need,<refdes>,<footprint>,<value>,[device])
  Help text: | Adds the given element if it doesn't already exist.
  Registered by: | n/a

  Arguments:

  Start | Indicates the start of an subcircuit list; call this before any Need actions.
  Need | Searches the board for an subcircuit with a matching refdes. If found, the value and footprint are updated. If not found, a new subcircuit is created with the given footprint and value.
  Done | Compares the list of subcircuits needed since the most recent Start with the list of subcircuits actually on the board. Any subcircuits that weren't listed are selected, so that the user may delete them.

  Placement of new subcircuits depends on conf node import/footprint_placement/method, which is a string containing a one word instruction that is one of:

  disperse | place all new subcircuits at randomized coordinates around location , within a distance configured in import/footprint_placement/disperse
  frame | place all new subcircuits close outside of the drawing area, "framing" the design

  Location is a string instruction specified by import/footprint_placement/location, the value is one of:

  (empty, no value) | place around the coordinates specified in coords import/footprint_placement/x and import/footprint_placement/y
  center | place around the center of the drawing area
  mark | place around the mark (or center of the drawing area if no mark present at the moment of import)

  Removal of excess subcircuits (the ones present on the board but not in the new netlist) depends on conf node import/footprint_removalt/method, which is a string containing a one word instruction that is one of:

  select (or empty) | select excess subcircuits (an {s r} after the import removes them)
  remove | automatically remove excess subcircuits
  list | no change on excess subcircuit data on the board, but open a view list dialog enumerating them

  Note: subcircuits with the nonetlist flag set or empty/missing refdes will not be taken as excess even if they are not present on the netlist.

## ElementSetAttr

  Syntax summary: | ElementSetAttr(refdes,name[,value])
  Help text: | Sets or clears an element-specific attribute.
  Registered by: | n/a

  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.

## ExecuteFile

  Syntax summary: | ExecuteFile(filename)
  Help text: | Run actions from the given file.
  Registered by: | n/a

  Lines starting with # are ignored.

## ExportOldConn

  Syntax summary: | ExportOldConn(AllConnections|AllUnusedPins|ElementConnections,filename)
  Help text: | Export galvanic connection data in an old, custom file format.
  Registered by: | export_oldconn HID

  Arguments:

  AllConnections | Save all connections to a file.
  AllUnusedPins | List all unconnected terminals to a file.
  ElementConnections | Save connections to the subcircuit at the cursor to a file.

## Flip

  Syntax summary: | Flip(Object|Selected)
  Help text: | Flip a subcircuit to the opposite side of the board.
  Registered by: | n/a

  Note that the location of the subcircuit 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 subcircuit is on the other side. When flipping multiple subcircuits, this retains their positions relative to each other, not their absolute positions on the board.

## FontXform

  Syntax summary: | FontXform(xform1, params..., [xform2, params...], ...)
  Help text: | Transform font graphics in fontmode (FontEdit)
  Registered by: | fontmode plugin

  Transform all glyphs of the current font while in fontmode (FontEdit()).

  The action sets up a 2d transformation matrix, initially an ident matrix, then applies each transformation from the arguments to this matrix. Finally it iterates through all glyphs and transforms drawing objects using this matrix. The origin of the transformation is the origin of the glyph cell, which is the top left corner (the top left grid crossing).

  Transformation arguments:

  arg | description
  --- | ---
  move, dx, dy | translate coordinates by dx;dy coords
  shear, sx, sy | shear coordinates by a factor of sx;sy (floating point numbers in decimal format); arc angles are not changed, only center point is moved
  scale, sx, sy | scale coordinates by a factor of sx;sy (floating point numbers in decimal format); arc radius is not scaled, only centerpoint is moved
  rotate, ang | rotate objects by ang degrees; arc angles are not changed, only center point is rotated; positive angles rotate CCW

  Example:

       FontXform(move, 0, 54mil,   shear, -0.15, 0,   move, 0, -54mil)

  This first moves each glyph 54 mil up, then shears them by 15% to the right then moves them back down 54 mil. The move is used to transform the base coordinate of the shear to the baseline of the font. But it really works the other way around: transformations always use the top left corner as as origin, but if glyph data is moved up, above cell top, it's the same as if we moved the transformation down by the same amount.

  Note: because transfomrations are applied to a matrix first, they need to be specified in reverse order. In the above example the last move is the one that moves everything up (negative y).

## FreeRotateBuffer

  Syntax summary: | FreeRotateBuffer([Angle])
  Help text: | 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.
  Registered by: | n/a

  Rotates the contents of the pastebuffer by an arbitrary angle. If no angle is given, the user is prompted for one.

## GfxMod

  Syntax summary: | GfxMod(transparent, [idpath, [#rrggbb]]) GfxMod(transparent, [idpath, [x, y]]) GfxMod(resize, [idpath, [pdx, pdy1, len]])
  Help text: | Modify a gfx object: set transparent pixel on the pixmap or resize by measurement
  Registered by: | n/a

  Commands:

  - transparent, no more args: interactive way for the user to specify the transparent color by a click
  - transparent, idpath, #rrggbb: specify transparent color
  - transparent, idpath, px, py: specify transparent color by pixel coordinates within the pixmap
  - resize, no more args: interactive resizer where the user clicks on two points of the pixmap on screen and specifies the real disatnce between them and the code resizes the pixmap to match that
  - resize, idpath, pdx, pdy, len: resize pixmap so that pixel distance pdx;pdy will match len coord units

## Import

  Syntax summary: | Import() Import([gnetlist|make[,source,source,...]]) Import(setnewpoint[,(mark|center|X,Y)]) Import(setdisperse,D,units)
  Help text: | Import schematics.
  Registered by: | oldactions plugin

  Deprecated. Please use importsch instead.

  For help on switching over, please read this: err0002

## ImportGUI

  Syntax summary: | ImportGUI()
  Help text: | Asks user which schematics to import into PCB.
  Registered by: | oldactions plugin

  Deprecated. Please use importsch instead.

  For help on switching over, please read this: err0002

## ImportSch

  Syntax summary: | ImportSch() ImportSch(reimport) ImportSch(setup, importer, [args...])
  Help text: | Import schematics/netlist.
  Registered by: | import_sch2 plugin

  Imports netlist (and optionally footprint references) from schematic(s) or netlist(s). Works from one or multiple input files. This action does not do file operations on its own, it is merely a dispatched to import plugins.

  The import configuration is normally stored in the config tree of the board file (on the design role of the conf system) and consists of:

  - the name of the importer that will load the input files
  - a list of arguments to the importer (strings, most often input file names)
  - misc settings, e.g. verbosity of the import

  When called without argument, or with the reimport the action will read the config and perform an import.

  When called with setup , the action will store the configuration read from the rest of the arguments:

      importsch
      (setup,
      importer
      ,
      args...
      )

  There can be zero or more arguments following the importer. The syntax and meaning of those arguments are specific to the importer, but is most usually the file name(s) to import from, e.g.

       ImportSch(setup, tEDAx, foo.tdx)

       ImportSch(setup, gnetlist, sheet1.sch, sheet2.sch)

  When called with dialog , the action will present a non-modal GUI dialog that allows changing the setup and performing the import.

## l

  Syntax summary: | l [name] [format]
  Help text: | Loads layout data.
  Registered by: | shand_cmd plugin

  Loads a new datafile (layout) and, if confirmed, overwrites any existing unsaved data. If no filename is specified a file select box will popup.

## LayerByStack

  Syntax summary: | LayerByStack(select, prev|next)
  Help text: | Layer operations based on physical layer stacking
  Registered by: | n/a

  First argument determines what to perform. When first argument is select , the second argument is either prev or next and the previous or next layer on the layer stack is selected. Note: layers are displayed in the layer stack order in the layer selector widget (normally on the left side of the main window) so prev/next is stepping up/down on that list.

## le

  Syntax summary: | le [name]
  Help text: | Loads an element (subcircuit, footprint) into the current buffer.
  Registered by: | shand_cmd plugin

  The filename is passed to the footprint loader. If no filename is specified a file select box will popup.

## LineNew

  Syntax summary: | LineNew([noundo,] data, layer, X1, Y1, X2, Y2, Thickness, Clearance, Flags)
  Help text: | Create a pcb line segment on a layer. For now data must be "pcb". Returns the idpath of the new object or 0 on error.
  Registered by: | act_draw

  Creates a new line object on target layer.

  The first argument is the usual optional "noundo". Then come the mandatory data and layer arguments for addressing the target layer. Coordinates x1, y1, x2 and y2 follow. Finally thickness, clearance coordinates and symbolic flag names passed as a string of comma separated list (can be empty).

## ListRats

  Syntax summary: | ListRats([view|print])
  Help text: | Display a list of rat lines
  Registered by: | report plugin

  Build and present a list of rat lines.

  The first argument is either view , in which case the list is presented on the GUI as a view list dialog, or print in which case rat line coordinates are printed in the message log. The view dialog approach allows quick navigation to the rat lines on GUI while the print approach allows better CLI integration.

  This action is provided to ease finding the last few remaining rat lines in a dense mostly routed board and is typically invoked after rats nest optimization (hotkey {c r} with the default menu file).

## Load

  Syntax summary: | Load() Load(Layout|LayoutToBuffer|ElementToBuffer|Netlist|Revert)
  Help text: | Load layout data from a user-selected file.
  Registered by: | dialogs plugin

  This action is a GUI front-end to the core's loadfrom action. If you happen to pass a filename, loadfrom is called directly. Else, the user is prompted for a filename to load, and then loadfrom is called with that filename.

## LoadFootprint

  Syntax summary: | LoadFootprint(filename[,refdes,value])
  Help text: | Loads a single footprint by name.
  Registered by: | n/a

  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.

## LoadFrom

  Syntax summary: | LoadFrom(Layout|LayoutToBuffer|SubcToBuffer|Netlist|Revert,filename[,format])
  Help text: | Load layout data from a file.
  Registered by: | n/a

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

  Arguments:

  Layout | Loads an entire PCB layout, replacing the current one.
  LayoutToBuffer | Loads an entire PCB layout to the paste buffer.
  ElementToBuffer | Loads the given footprint file into the paste buffer. Footprint files contain only a single subcircuit definition in one of the various supported file formats.
  Netlist | Loads a new netlist, replacing any current netlist.
  Revert | Re-loads the current layout from its disk file, reverting any changes you may have made.

## LoadTtfGlyphs

  Syntax summary: | LoadTtfGlyphs(filename, srcglyps, [dstchars], [outline|polygon], [scale], [offset])
  Help text: | Loads glyphs from an outline ttf in the specified source range, optionally remapping them to dstchars range in the pcb-rnd font
  Registered by: | ttf importer

  Import a range of glyphs from ttf outline font into the current font as symbols, starting from a specific character position. Note: pcb-rnd font symbols are not unicode code poitns, but consists of a single, 8 bit ASCII code page, thus values above 255 are invalid as destination symbol code.

  The srcglyph argumnet is a single character description or a pair of character descriptions separated with two dots (".."). In the former case the import is a single glyph, in the latter case the import is the whole range between the two characters, inclusive (one or more glyphs).

  The dstchars argumnet is always a single character description , addressing within the 0..255 range of the pcb-rnd font. This argment determines the first destination symbol that is going to be overwritten. If srcglyph specifies multiple characters, dstchars is internally stepped after each glyp import, up to 255, where the import stops.

  A character description addresses a code point on the input or a character code on the output, using one fo the following syntax variants:

  - 'A' is converted to 65 (as a single charatcer using the 8 bit ASCII table)
  - is converted as decimal number 10
  - is converted as hexadecimal number, to 16
  - U+10 is converted as hexadecimal number, to 16
  - anything else is taken as a single character and is converted as it was wrapped in ''

  The 4th argument is either polygon or line. When it is polygon, the glyph is imported as a polygon (with or without holes). When it is line, all contours of the glyph is imported as a series of lines. When not specified, it defaults to polygon.

  Finally, scale and offset specifies the transformation during the import. Each argument is either a single number or a pair of numbers separated with comma or semicolon or / or * or x, and specify the x and y components of the transformation. When only the x component is specified, y is assumed to be the same (this is useful for scale).

## LoadVendorFrom

  Syntax summary: | LoadVendorFrom(filename, [yes|no])
  Help text: | Loads the specified vendor lihata file. If second argument is "yes" or "pure", load in pure mode without side effects: do not reset or apply, only incrementally load.
  Registered by: | vendor drill mapping

  Arguments:

  filename | Name of the vendor lihata file. If not specified, the user will be prompted to enter one.
  pure (yes or no) | If "yes" or "pure", load in pure mode without side effects: do not reset or apply, only incrementally load.

## m

  Syntax summary: | m [name]
  Help text: | Loads a layout into the current buffer.
  Registered by: | shand_cmd plugin

  If no filename is specified a file select box will popup.

## MarkCrosshair

  Syntax summary: | MarkCrosshair() MarkCrosshair(Center)
  Help text: | Set/Reset the pcb_crosshair mark.
  Registered by: | n/a

  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 Center argument is given, the mark is moved to the current cursor location.

## Mode

  Syntax summary: | Tool(Arc|Arrow|Copy|InsertPoint|Line|Lock|Move|None|PasteBuffer) Tool(Poly|Rectangle|Remove|Rotate|Text|Thermal|Via) Tool(Press|Release|Cancel|Stroke) Tool(Save|Restore)
  Help text: | Change or use the tool mode.
  Registered by: | n/a

  This command is a compatibility alias to tool .

## MorphPolygon

  Syntax summary: | pcb_poly_morph(Object|Selected)
  Help text: | Converts dead polygon islands into separate polygons.
  Registered by: | n/a

  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.

## MoveLayer

  Syntax summary: | MoveLayer(old,new) MoveLayer(lid,group,gid)
  Help text: | Moves/Creates/Deletes Layers.
  Registered by: | n/a

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

  Arguments:

  old

  The is the layer number to act upon. Allowed values are:
  - c = Currently selected layer.
  - -1 = Create a new layer.
  - number = An existing layer number.

  new

  Specifies where to move the layer to. Allowed values are:
  - -1 = Deletes the layer.
  - up = Moves the layer up (TODO: is this supported?)
  - down = Moves the layer down (TODO: is this supported?)
  - step+ = Moves the layer towards the end of its group's list.
  - step- = Moves the layer towards the beginning of its group's list.
  - c = Creates a new layer.
  - grp gid = move layer into group; target group ID is the 3rd argument

## MoveObject

  Syntax summary: | pcb_move_obj(X,Y,[units])
  Help text: | Moves the object under the crosshair.
  Registered by: | n/a

  The X and Y are treated like delta if they are prefixed by + or -, otherwise, they are absolute. Units can be mil or mm and is used when X and Y have no unit specified. If no unit unspecified in coords or units, nanometer is assumed.

## MoveToCurrentLayer

  Syntax summary: | MoveToCurrentLayer(Object|SelectedObjects)
  Help text: | Moves objects to the current layer.
  Registered by: | n/a

  Note that moving an subcircuit from a component layer to a solder layer, or from solder to component, won't automatically flip it. Use the flip action to do that.

## netlist

  Syntax summary: | Net(find|select|rats|norats|ripup|addrats|clear[,net[,pin]]) Net(freeze|thaw|forcethaw) Net(swap) Net(add,net,pin) Net([rename|merge],srcnet,dstnet) Net(remove,netname)
  Help text: | Perform various actions on netlists.
  Registered by: | n/a

  Each of these actions apply to a specified set of nets. net and 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, then the pattern is tried as a regular expression.

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

  freeze , thaw and 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.

  Argument summary:

  find | Nets which apply are marked @emph{found} and are drawn in the connected-color color.
  select | Nets which apply are selected (added to existing selections).
  unselect | Nets which apply are unselected (removed from existing selections).
  rats | Nets which apply are marked as available for the rats nest.
  norats | Nets which apply are marked as not available for the rats nest.
  allrats | Mark all nets available for the rats nest.
  allnorats | Mark all nets not available for the rats nest.
  clear | Clears the netlist.
  ripup | Remove all non-subcircuit-part copper object that is connected to a net.
  add | Add the given pin to the given netlist, creating either if needed.
  AddRats | Calculate and add all rats required for finishing the named network.
  swap | Swap the connections one end of two selected rats and pins.
  sort | Called after a list of add's, this sorts the netlist.
  freeze thaw forcethaw | Temporarily prevents changes to the netlist from being reflected in the GUI.
  rename | Change the name of a network (with back annotation)
  merge | Move all terminal connections from the source network (first arg) to the destination network (with back annotation)
  remove | Remove all connections of a net (with back annotation); also remove the net.

## New

  Syntax summary: | New([name])
  Help text: | Starts a new layout.
  Registered by: | n/a

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

## OpenemsExcitation

  Syntax summary: | OpenemsExcitation([interactive]) OpenemsExcitation(select, excitationname) OpenemsExcitation(set, [excitationnme], paramname, paramval) OpenemsExcitation(get, [excitationnme], paramname)
  Help text: | Select which openEMS excitation method should be exported and manipulate the associated parameters. When invoked without arguments a dialog box with the same functionality is presented.
  Registered by: | openems HID

  When invoked without argument or with interactive a dialog box is presented, allowing the user to do the same operations as with the action.

  If the first argument select , further OpenEMS exports will use the excitation named in the excitationname argument (in short: the excitation is selected).

  Arguments set and get is used to read or change an excitation parameter named in paramname . When excitationname is not set, they operate on the currently selected excitation. For set the paramval argument is mandatory.

  Note: the code remembers all settings for all excitements, not only the excitement that is currently selected. The selection and all parameters are saved as board attributes.

## PadstackReplace

  Syntax summary: | PadstackReplace(object|selected, buffer|tool)
  Help text: | Replace padstack prototypes from buffer's first padstack or from the via tool
  Registered by: | n/a

  Replacing padstacks, especially within multiple subcircuits, is a tedious task because the prototype of the new padstack needs to be added in each local padstack prototype library (e.g. one per subcircuit). The PadstackReplace() action can automate this.

  First argument is destination padstack, the object that is going to be changed. It is either object for a single padstack under the cursor, or selected for all selected padstacks. Both work on padstacks within subcircuits.

  The second argument is source padstack, from which the prototype (geometry) is copied. It can be tool for using the via tool's padstac prototype (which is usually from the current style) or buffer which uses the first padstack found in the current buffer.

## PasteBuffer

  Syntax summary:

  PasteBuffer(AddSelected|MoveSelected|Clear|1..PCB_MAX_BUFFER) PasteBuffer(Rotate, 1..3) PasteBuffer(Convert|Restore|Mirror) PasteBuffer(ToLayout, X, Y, units) PasteBuffer(ToLayout, crosshair) PasteBuffer(Save, Filename, [format], [force]) PasteBuffer(SaveAll, Filename, [format]) PasteBuffer(LoadAll, Filename) PasteBuffer(Push) PasteBuffer(Pop) PasteBuffer(GetSource, [1..PCB_MAX_BUFFER])

  Help text: | Various operations on the paste buffer.
  Registered by: | n/a

  There are a number of paste buffers; the actual limit is a compile-time constant PCB_MAX_BUFFER . It is normally 5 . One of these is the "current" paste buffer, often referred to as "the" paste buffer. Arguments:

  AddSelected | Copies the selected objects to the current paste buffer.
  Clear | Remove all objects from the current paste buffer.
  Convert | Convert the current paste buffer to an subcircuit.
  Restore | Convert any subcircuit in the paste buffer back to plain objects.
  Mirror | Flip all objects in the paste buffer vertically (up/down flip). To mirror horizontally, combine this with rotations.
  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).
  Normalize | Set the buffer origin to the center of the paste buffer bounding box. This is useful especially if an import plugin loaded objects in the buffer with a large offset.
  Save | Saves subcircuits in the current buffer to the indicated file. If format is specified, try to use that file format, else use the default. If force is specified, overwrite target, don't ask.
  SaveAll | Saves all content of the current buffer to the indicated file. If format is specified, try to use that file format, else use the default.
  LoadAll | Loads a previously saved paste buffer into the current buffer from the indicated file.

  ToLayout

  Pastes objects in the current buffer to the indicated X, Y coordinates in the layout. The X and Y are treated like delta is for many other objects. For each, if it's prefixed by + or -, then that amount is relative to the last location. Otherwise, it's absolute. If units is unspecified, units are PCB's internal units, currently nanometer. If "crosshair" is used instead of coordinates, the paste happens at the current crosshair coords.

  1..PCB_MAX_BUFFER | Selects the given buffer to be the current paste buffer.
  GetSource | Returns the source file path the buffer is loaded from or nil if there is none. The return value is a string, usable from user scripts.
  Push | Push the index of the currently active paste buffer into an internal stack. The stack is not board-specifiec.
  Pop | Pop an index from the internal stack and set currently active paste buffer index accordingly.

## PolyBool

  Syntax summary: | PolyBool([noundo,] unite|isect|sub, [poly1, poly2, [poly...]])
  Help text: | Perform polygon boolean operation on the clipped polygons referred. A poly is either and idpath, selected, found or object (for the object under the cursor). When not specified, two object polygons are used.
  Registered by: | act_draw

  The boolean operation argument is one of these:

  - unite: calculate the union of the polygons
  - isect: calculate the intersection of all polygons; the result is the area where all argument polygons are present
  - sub: subtract subsequent polygons from the first polygon

  A polygon is a pcb layer object, that is: if it's fullpoly, it may have multiple islands. The code operates on the clipped shape of the input polygons, not on the 'as drawn shape'. The result is zero or more polygon layer objects, each with a single island, created on the current layer.

  The rest of the arguments will build a flat list of polygon objects to work on and need to address at least two polygons. Each argument may be one of:

  - object: the user needs to click an object using the GUI
  - selected: all selected polygons are appended to the list
  - found: all found (green highlight) polygons are appended to the list
  - ipdath : address a specific polygon

  Note: for the sub operation the first polygon is special, so order of attributes matter. When using selected or found to address polygons, if multiple polygons are selected or found at the time, the order they end up added to the operation object list is undefined.

  Input polygons are unchanged, new polygons are created on the current layer.

  Demo video: PolyBool(sub) mini-howto.

## PolyCombine

  Syntax summary: | n/a
  Help text: | n/a
  Registered by: | polycombine plugin

  The selected polygons are combined together according to the ordering of their points.

## Polygon

  Syntax summary: | Polygon(Close|CloseHole|PreviousPoint)
  Help text: | Some polygon related stuff.
  Registered by: | n/a

  Argument:

  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.
  CloseHole | Creates the final segment of the polygon hole. This may fail if clipping to 45 degree lines is switched on, in which case a warning is issued.
  PreviousPoint | Resets the newly entered corner to the previous one. The Undo action will call Polygon(PreviousPoint) when appropriate to do so.

## PolyStitch

  Syntax summary: | n/a
  Help text: | n/a
  Registered by: | polystitch plugin

  The polygon under the cursor (based on closest-corner) is stitched together with the polygon surrounding it on the same layer.

  Use with pstoedit conversions where there's a "hole" in the shape - select the hole.

## Popup

  Syntax summary: | Popup(MenuName, [obj-type])
  Help text: | Bring up the popup menu specified by MenuName, optionally modified with the object type under the cursor.
  Registered by: | lib_hid_pcbui/actions

  Pops up the specified menu. The menu must have been defined in the popups subtree in the menu lht file. If the second argument is specified, the menu name is modified by runtime data:

  obj-type | append a dash and the object type name (e.g. "-line") for the object currently under the cursor

## preunload

  Syntax summary: | n/a
  Help text: | n/a
  Registered by: | n/a

  preunload is an optional action scripts may provide. When present, it is called by pcb-rnd as the last call to the script before the script is unloaded. It has two purposes:

  - give scripts a chance to clean up, uninit and unregister
  - give scripts a chance to perist their state

  State persisting is achieved through returning a string from this action. That string is then saved by pcb-rnd under the scripts' load ID (as specified by the user). In a later script load, the script with the same ID may read the persistent data frolm disk using the scriptpersistency (read) action and can remove the save using the scriptpersistency (remove) action.

  It should never be called by the user or other code or other actions.

## PrintCalibrate

  Syntax summary: | PrintCalibrate()
  Help text: | DEPRECATED: Calibrate the printer.
  Registered by: | dialogs plugin

  Used to help with printer calibrataion, but did not really work properly for at least a decade. This feature was removed after pcb-rnd 2.3.2. There is an alternative manual calibration method.

## Puller

  Syntax summary: | pcb_act_Puller()
  Help text: | Pull an arc-line junction tight.
  Registered by: | puller plugin

  The 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.

## q

  Syntax summary: | q
  Help text: | Quits the application after confirming.
  Registered by: | shand_cmd plugin

  If you have unsaved changes, you will be prompted to confirm (or save) before quitting, unless the action name included a !.

## Quit

  Syntax summary: | Quit()
  Help text: | Quits the application after confirming.
  Registered by: | n/a

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

## Redo

  Syntax summary: | redo()
  Help text: | Redo recent "undo" operations.
  Registered by: | n/a

  The redo action 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.

## RefdesText

  Syntax summary: | RefdesText(object|selected, create)
  Help text: | Manipulate refdes text object on subcircuit(s)
  Registered by: | n/a

  First argument determines scope and is either object (for a single subcircuit under the cursor) or selected (for all selected subcircuits).

  Second argument is:

  - create : create a new refdes text (even if one already exists) on the first silk layer of the given subcircuit

## RenumberBlock

  Syntax summary: | RenumberBlock(old_base,new_base)
  Help text: | Renumber selected subcircuit refdes attributes by adding (new_base-old_base).
  Registered by: | renumber plugin

  Example: RenumberBlock(oldnum,newnum)

  All selected subcircuit refdes attributes are renumbered by adding (newnum-oldnum) to the existing number.

  Example: RenumberBlock(100,200)
  will change R213 to R313.

## RenumberBuffer

  Syntax summary: | RenumberBuffer(old_base,new_base)
  Help text: | Renumber buffer subcircuit refdes attributes by adding (new_base-old_base).
  Registered by: | renumber plugin

  Example: RenumberBuffer(oldnum,newnum)

  Same as renumberblock , but the paste buffer is renumbered.

## ReplaceFootprint

  Syntax summary: | ReplaceFootprint([Selected|Object], [footprint], [dumb])
  Help text: | Replace the footprint of the selected components with the footprint specified.
  Registered by: | n/a

  Replace footprint(s) from the library or buffer, in-place (preserving the original subcircuit's location, rotation and metadata) and append the replacement to the back annotation changeset.

  If first argument is selected , replace all selected subcircuits with the new footprint; if it is object , replace only one subcircuit, under the cursor.

  If the second argument is a footprint name, load it from the library. If it is @buffer , use the subcircuit in the current buffer (there must be exactly 1 subcircuit in the buffer). If it is empty or not specified, the user is asked for a footprint.

  If the third argument is dumb the location and rotation of the original subcircuit is not preserved (but all metadata and board side are preserved). A dumb replacement also omits creating back annotation.

## Report

  Syntax summary: | Report([DrillReport|FoundPins|NetLengthTo]) Report(NetLength, [netname]) Report(Object|Subc, [log]) Report(AllNetLengths, [unit])
  Help text: | Produce various report.
  Registered by: | report plugin

  Arguments:

  Object | The object under the crosshair will be reported, describing various aspects of the object.
  DrillReport | A report summarizing the number of drill sizes used, and how many of each, will be produced.
  FoundPins | A report listing all pins and pads which are marked as "found" will be produced.
  NetLength | The name and length of the net under the crosshair will be reported to the message log. An optional parameter specifies the netname; when present the length of the named network is printed, else the net under the cursor is used.
  AllNetLengths | The name and length of the net under the crosshair will be reported to the message log. An optional parameter specifies the unit name (e.g. mm)

## reportdialog

  Syntax summary: | n/a
  Help text: | n/a
  Registered by: | n/a

  This is a shortcut for report ( Object ).

## RipUp

  Syntax summary: | RipUp(All|Selected|Element)
  Help text: | Ripup auto-routed tracks
  Registered by: | n/a

  Arguments:

  All | Removes all lines and vias which were created by the autorouter.
  Selected | Removes all selected lines and vias which were created by the autorouter.

## rn

  Syntax summary: | rn [name]
  Help text: | Reads netlist.
  Registered by: | shand_cmd plugin

  If no filename is given a file select box will pop up.

## Rotate90

  Syntax summary: | Rotate90(steps)
  Help text: | Rotates the object under the crosshair by 90 degree steps.
  Registered by: | n/a

  Rotates the object under the mouse pointer by 90 degree steps . steps must be an integer between -3 and +3.

## RouteStyle

  Syntax summary: | RouteStyle(style_id|style_name|@current, [set|get|del], [trace-thickness|trace-clearance|text-thickness|text-scale|font|via-proto|name], [value]]) RouteStyle(new, [name])
  Help text: | Without second argument: copies the indicated routing style into the current pen; with second argument sets or gets a field of the routing style.
  Registered by: | n/a

  Reads or writes route style properties.

  If the first argument is new , a new style is created, optionally using the name provided as the second argument; else the following happens.

  The first argument addresses the style and is one of:

  - an integer greater than zero: style ID (styles are counted from 1)
  - @current, which will pick the style currently selected
  - an arbitrary style name, which will pick the first style with matching name

  The second argument is one of:

  - set , which will modify the addressed style using the 4th argment value
  - get , where the 4th argument is omitted and the return value of the action holds the resulting value of the query
  - del , which will remove the style addressed.

  The 3rd argument addresses the property of the style.

  Note: all operations by this action are undoable.

## RtreeList

  Syntax summary: | RtreeList(data_addr, layer_addr|global, rtree_name, [x1, y1, x2, y2])
  Help text: | Return a list of idpaths for objects overlapping with the box specified (empty list if no object is found). Error is indicated by returning nil. If coordinates are not specified the whole tree is searched.
  Registered by: | act_read

  The first argument selects the data to operate on.

  The second argument is either the string global or is a layer address . The rtree name in the third argument must correspond to the value of this argument: some of the rtrees are global, others are per layer.

  The third argument is the name of the rtree to search. The following rtrees are available:

  name | scope | description
  --- | --- | ---
  padstack | global | padsatck objects (typically used for vias, pins, pads)
  subc | global | subcircuit objects
  rat | global | rat lines
  line | layer | line objects
  text | layer | text objects
  polygon | layer | polygon objects
  arc | layer | arc objects
  gfx | layer | gfx (bitmap/pixmap) objects

  Note: rtrees are global to the given scope, e.g. the padstack rtree holds all padstacks (inside and outside of subcircuits) and a layer's line rtree holds all line objects that appear on the given layer (inside and outside of subcircuits).

  Optionally four more arguments may be supplied; when present, these are 4 coordinates that specify the bounding box of the search by the x and y coordinates of top left and bottom right corners. When these coordinates are not specified all objects on the rtree is listed.

## s

  Syntax summary: | s [name] w [name]
  Help text: | Saves layout data.
  Registered by: | shand_cmd plugin

  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.

## Save

  Syntax summary: | Save() Save(Layout) Save(LayoutAs, [path]) Save(AllConnections|AllUnusedPins|ElementConnections, [path]) Save(PasteBuffer, [path]) Save(DialogByPattern, pcb|footprint|font|buffer, none|board|fp, prompt, [default_pattern])
  Help text: | Save layout data to a user-selected file.
  Registered by: | dialogs plugin

  This action is a GUI front-end to the core's saveto action. If you happen to pass a filename then saveto is called directly. Else, the user is prompted for a filename to save, and then saveto is called with that filename.

  The DialogByPattern mode is intended for scripts and core: it presents a dialog box with format selection and listing patterns, but does not perform any real file operation just returns a filename*format string.

## SaveLib

  Syntax summary: | SaveLib(file|dir, board|buffer, [filename], [fmt])
  Help text: | Saves all subcircuits to a library file or directory from a board or buffer.
  Registered by: | n/a

  Useful when multiple subcircuits should be saved to be reused as a library. When first argument is dir , each subcircuit is saved in a separate, numbered file. If the first argument is file and the target file format has library support, all subcircuits are saved in the same file, as a library.

  If a single subcircuit from buffer needs to be saved to be a footprint, use the saveto action with first argument set to PasteBuffer.

## SaveTo

  Syntax summary: | SaveTo(Layout|LayoutAs,filename,[fmt]) SaveTo(PasteBuffer,filename,[fmt])
  Help text: | Saves data to a file.
  Registered by: | n/a

  Arguments:

  Layout | Saves the current layout.
  LayoutAs | Saves the current layout, and remembers the filename used.
  PasteBuffer | Save the subcircuit from the active Buffer to a file. The buffer needs to contain exactly one subcircuit. This is the graphical way to create a footprint. If multiple subcircuits needs to be saved, use the savelib action.
  AllConnections, AllUnusedPins, ElementConnections | obsolete arguments, kept for compatibility; please use exportoldconn instead.

## Select

  Syntax summary: | Select(Object, [idpath]) Select(ToggleObject) Select(All|Block|Connection|Invert) Select(Convert)
  Help text: | Toggles or sets the selection.
  Registered by: | n/a

  Arguments:

  Object ToggleObject | If second argument is present, select the object addressed by that idpath, else selects the object under the cursor.
  Block | Selects all objects in a rectangle indicated by the cursor.
  All | Selects all objects on the board.
  Connection | Selects all connections with the ``found'' flag set.
  Convert | Converts the selected objects to a subcircuit. This uses the highest numbered paste buffer.
  Invert | Invert selection: anything that was not selected becomes selected, everything that was selected becomes unselected. Locked objects are not affected.

## SelectLayer

  Syntax summary: | SelectLayer(1..MAXLAYER|Silk|Rats)
  Help text: | Select which layer is the current layer.
  Registered by: | n/a

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

## SetFlag

  Syntax summary: | SetFlag(Object|Selected|SelectedObjects, flag) SetFlag(SelectedLines|SelectedPins|SelectedVias, flag) SetFlag(SelectedPads|SelectedTexts|SelectedNames, flag) SetFlag(SelectedElements, flag) flag = thermal | join
  Help text: | Sets flags on objects.
  Registered by: | n/a

  Turns the given flag on, regardless of its previous setting. See changeflag .

  Example: SetFlag(SelectedPins,thermal)

## SetSame

  Syntax summary: | SetSame()
  Help text: | Sets current layer and sizes to match indicated item.
  Registered by: | n/a

  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, clearance, etc) according to that item.

## SetThermal

  Syntax summary: | SetThermal(Object|SelectedPins|SelectedVias|Selected, Style)
  Help text: | Set the thermal (on the current layer) of padstacks to the given style. Style is one of: 0: means no thermal. 1: horizontal/vertical, round. 2: horizontal/vertical, sharp. 3: is a solid connection to the polygon. 4: (invalid). 5: diagonal, round. 6: diagonal, sharp. noshape: no copper shape on layer
  Registered by: | n/a

  This changes how/whether padstacks connect to any rectangle or polygon on the current layer. The first argument can specify one object, or all selected padstacks. The second argument specifies the style of connection.

  Thermal styles:

  0 | no connection,
  1 | horizontal & vertical fingers with round edges,
  2 | horizontal & vertical fingers with sharp edges,
  3 | solid connection,
  4 | invalid, do not use
  5 | 45 degree fingers with rounded corners.
  6 | 45 degree fingers with sharp edges,
  noshape | remove copper shape on layer

  Padstacks may have thermals whether or not there is a polygon available to connect with. However, they will have no visible effect until a polygon is drawn around the padstack.

## SetValue

  Syntax summary: | SetValue(Grid|Line|LineSize|Text|TextScale, delta)
  Help text: | Change various board-wide values and sizes.
  Registered by: | n/a

  Arguments:

  Grid | Sets the grid spacing.
  Line LineSize | Changes the thickness of new lines.
  Text TextScale | Changes the size of new text.

## smartdisperse

  Syntax summary: | SmartDisperse([All|Selected])
  Help text: | Disperse subcircuits into clusters, by netlist connections
  Registered by: | smartdisperse plugin

  Improve the initial dispersion of subcircuits by choosing an order based on the netlist, rather than the arbitrary subcircuit order. This isn't the same as a global autoplace, it's more of a linear autoplace. It might make some useful local groupings. For example, you should not have to chase all over the board to find the resistor that goes with a given LED.

## SwapSides

  Syntax summary: | SwapSides(|v|h|r, [S])
  Help text: | Swaps the side of the board you're looking at.
  Registered by: | lib_hid_pcbui/actions

  This action changes the way you view the board (flipping the board).

  Arguments:

  v | Flips the board over vertically (up/down); try to keep location on screen.
  h | Flips the board over horizontally (left/right), like flipping pages in a book.
  r | Rotates the board 180 degrees without changing sides.

  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 pcb_true silk, and which are drawn as the "invisible" layer. It also determines which solder mask you see.

  If S is specified as a second argument, 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.

## TextNew

  Syntax summary: | TextNew([noundo,] data, layer, fontID, x, y, rot, scale, thickness, text_string, flags)
  Help text: | Create a pcb text on a layer. For now data must be "pcb". Font id 0 is the default font. Thickness 0 means default, calculated thickness. Scale=100 is the original font size. Returns the idpath of the new object or 0 on error.
  Registered by: | act_draw

  Creates a new text object on target layer.

  The first argument is the usual optional "noundo". Then come the mandatory data and layer arguments for addressing the target layer. Font ID is an integer, use 0 for default. Placement coordinates x, y follow. Rot is an angle in degrees. Scale is an integer in percentage (100 being normal sized text). Finally thickness, clearance coordinates, text string and symbolic flag names passed as a string of comma separated list (can be empty).

## ToggleView

  Syntax summary: | ToggleView(1..MAXLAYER) ToggleView(layername) ToggleView(Silk|Rats|Pins|Vias|BackSide) ToggleView(All, Open|Vis, Set|Clear|Toggle)
  Help text: | Toggle the visibility of the specified layer or layer group.
  Registered by: | n/a

  If you pass an integer, that layer is specified by index (the first layer is 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.

## Undo

  Syntax summary: | undo() undo(ClearList|FreezeSerial|UnfreezeSerial|FreezeAdd|UnfreezeAdd|IncSerial|GetSerial|Above)
  Help text: | Undo recent changes.
  Registered by: | n/a

  The unlimited undo feature of pcb-rnd allows you to recover from most operations that materially affect you work. Calling pcb_undo without any parameter recovers from the last (non-undo) operation. ClearList is used to release the allocated memory. ClearList is called whenever a new layout is started or loaded. See also redo .

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

  The following arguments are intended for scripting:

  - FreezeSerial: stop increasing the undo serial number
  - UnFreezeSerial: stop increasing the undo serial number
  - FreezeAdd: start adding operations to the undo list again
  - UnFreezeAdd: start adding operations to the undo list again
  - IncSerial: increase the undo serial number (operations with the same serial number are batched); a typical sequence for batching operations is: Undo(FreezeSerial); ...; Undo(UnFreezeSerial); Undo(IcSerial)
  - GetSerial: return the current undo serial
  - GetNum: return the number of undo slots currently allocated
  - Above, sernum: perform undo of all operations with serial number higher than sernum

## Unselect

  Syntax summary: | Unselect(All|Block|Connection)
  Help text: | Unselects the object at the pointer location or the specified objects.
  Registered by: | n/a

  Arguments:

  All | Unselect all objects.
  Block | Unselect all objects in a rectangle given by the cursor.
  Connection | Unselect all connections with the "found" flag set.

## w

  Syntax summary: | s [name] w [name]
  Help text: | Saves layout data.
  Registered by: | shand_cmd plugin

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

## wq

  Syntax summary: | wq
  Help text: | Saves the layout data and quits.
  Registered by: | shand_cmd plugin

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

## Zoom

  Syntax summary: | Zoom() Zoom([+|-|=]factor) Zoom(x1, y1, x2, y2) Zoom(?) Zoom(get) Zoom(found|selected)
  Help text: | GUI zoom
  Registered by: | lib_hid_pcbui/actions

  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, factor specifies a change in zoom factor. It may be prefixed by + , - , = to change how the zoom factor is modified (relative or absolute). The factor is a floating point number, such as 1.5 or 0.75 .

  Alternatively a box can be specified with 4 coordinates and zoom will set the zoom level (and modifies pan) so that the given box of the design is visible and as large as possible in the current window.

  Arguments:

  (no argument) | Without argments: zoom to board extents.
  +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.
  -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.
  =factor | The @var{factor} is an absolute zoom factor; the unit for this value is "PCB units per screen pixel". Since PCB units are nanometer, a factor of 1000 means 1 micrometer per pixel (TODO: test this).
  x1, y1, x2, y2 | Zoom to the specified portion of the design, described as a rectangle (using board space coordinates)
  selected | Zoom and pan so that all selected objects are on the screen.
  found | Zoom and pan so that all found objects are on the screen.
  ? | Print the current zoom level in the message log (as an info line).
  get | Return the zoom level as an FGW_DOUBLE (useful for scripts).

  Note that zoom factors of zero are silently ignored.

# librnd actions (common to Ringdove)

## AddTimer

  Syntax summary: | AddTimer(action, period, [repeat], [userdata])
  Help text: | Add a new timer
  Registered by: | script plugin

  This action is intended for scripts to create async timers. Note: timers do not work with the batch HID (no callback issued ever).

  Creates a timer that executes an action (by name) periodically. Period is a real number specified in seconds. Internal timer resolution is in the order of 0.1 second.

  If repeat is not specified or is less than 1, the timer is repeated indefinitely. If the optional userdata string is specified, it is also passed to the action.

  The action is specified only by a name, call arguments are always the following:

  - now: the current UNIX time in a floating point number
  - integer: count back remaining number of calls, including the current call; 1 means this was the last call; 0 means infinite number of calls will follow
  - userdata or empty string

  Action shall return integer 0 on success. If the action does not exist or returns anything else, the timer is uninstalled.

  There can be any number of timers in parallel.

## AnyLoad

  Syntax summary: | AnyLoad([path])
  Help text: | Load "anything" from path (or offer a file selectio dialog if no path specified)
  Registered by: | n/a

  Loads an anyload.lht file or any lihata document that can be handled by the anyload system (mostly settings and setting-like states, e.g. config, vendor drill map, DRC and user scripts).

  When called without arguments a file selection dialog is popped up for selecting the file to load.

  More info on this mechanism in the knowledge pool node of anyload.

## Benchmark

  Syntax summary: | Benchmark()
  Help text: | Benchmark the GUI speed.
  Registered by: | n/a

  This action is used to speed-test the GUI rendering. 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, in average.

## Center

  Syntax summary: | Center()
  Help text: | Moves the pointer to the center of the window.
  Registered by: | lib_hid_common plugin

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

## Cursor

  Syntax summary: | Cursor(Type,DeltaUp,DeltaRight,Units)
  Help text: | Move the cursor.
  Registered by: | n/a

  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 DeltaUp may move the cursor away from the board origin if the board is inverted (flipped, looked from the bottom).

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

  Units can be one of the following:

  mil mm | The cursor is moved by that amount, in board units.
  grid | The cursor is moved by that many grid points.
  view | The values are percentages of the viewport's view. Thus, a pan of 100 would scroll the viewport by exactly the width of the current view.
  design | The values are percentages of the board size. Thus, a move of 50,50 moves you halfway across the board.
  board | Same as design (for backward compatibility)

## dowindows

  Syntax summary: | n/a
  Help text: | n/a
  Registered by: | n/a

  Argument:

  1 Layout | Open the layout window. Since the layout window is always shown anyway, this has no effect.
  2 Library | Open the library window.
  3 Log | Open the log window.
  4 Netlist | Open the netlist window.
  5 Preferences | Open the preferences window.
  6 DRC | Open the DRC violations window.
  7 Search | Open the advanced search window.

## GetXY

  Syntax summary: | GetXY([message, [x|y]])
  Help text: | Get a coordinate. If x or y specified, the return value of the action is the x or y coordinate.
  Registered by: | n/a

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

## ListScripts

  Syntax summary: | ListScripts([pat])
  Help text: | List fungw scripts, optionally filtered wiht regex pat.
  Registered by: | script plugin

  Print one line in the log for each currently loaded script. If pat is specified, filter the list using pat as a case sensitive extended regex on script ID, file name and language (list only scripts that match with any of these fields).

## LiveScript

  Syntax summary: | LiveScript([new], [name]) LiveScript(load|save, name, [filame]) LiveScript(run|stop|rerun|undo, name)
  Help text: | Manage a live script
  Registered by: | script plugin

  The first argument determines what operation the action performs and how subsequent arguments are interpreted:

  new, [name] | Create a new live script and open a new live script dialog. name is an unique live script name that identifies the window. If not specified, "default" is used"
  load, name, [filename] | Replace the script source in the LiveScript window identified by name with the content loaded from a file. If filename is not specified, open a file selector dialog.
  save, name, [filename] | Save the script source in the LiveScript window identified by name to a file. If filename is not specified, open a file selector dialog.
  run, name | Run the script in the LiveScript window identified by name .
  stop, name | Stop the script in the LiveScript window identified by name , if ti is running in persistent mode.
  undo, name | Undo the "init changes" of the script in the LiveScript window identified by name . Init changes are those board changes the script has done while running its initialization section. Live script undo is possible only if there was no user edit after the script finished.
  rerun, name | Stop, undo and run the script in the LiveScript window identified by name .

## LoadScript

  Syntax summary: | LoadScript(id, filename, [language])
  Help text: | Load a fungw script
  Registered by: | script plugin

  id is an arbitrary string assigned by the user. id must be unique per application session per script and may contain alphanumeric characters and undescrore.

  fn is the file name of the script, which is a path. Librnd does not do any search, it only opens the path as specified.

  lang is the scripting language, as in fungw plugin name . When not specified, the code makes a guess (based on the file name).

## Message

  Syntax summary: | message([ERROR|WARNING|INFO|DEBUG,] message)
  Help text: | Writes a message to the log window.
  Registered by: | n/a

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

  If there are 2 or more arguments and the first argument matches, in a case sensitive manner, one of the below keywords, the message is registered on the specified error level. Else the PCB_MSG_INFO error level is used.

  first argument | erro level
  --- | ---
  ERROR | PCB_MSG_ERROR
  WARNING | PCB_MSG_WARNING
  INFO | PCB_MSG_INFO
  DEBUG | PCB_MSG_DEBUG

## onliner

  Syntax summary: | n/a
  Help text: | n/a
  Registered by: | n/a

  The oneliner action is designed for quick execution of short, trivial scripts, such as a for loop for repeating an action. It supports any scripting language currently availabel through fungw. Each oneliner is an independent script context - variables, functions and other global states do not persist.

  This group of actions offers three forms:

  - oneliner ( lang , script ) - execute the script in the language specified
  - lang(script) - shorthand for the above
  - lang - switch the command line interpreter to execute one-liners in the given language, until /exit

  For example, a simple calculation using awk can be done in three ways:

  - oneliner(awk, 'print 42*3')
  - awk('print 42*3')
  - awk , then print 42*3 , then /exit

## Pan

  Syntax summary: | Pan(Mode)
  Help text: | Start or stop panning (Mode = 1 to start, 0 to stop)
  Registered by: | lib_hid_common plugin

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

## Print

  Syntax summary: | Print()
  Help text: | Present the print export dialog for printing the layout from the GUI.
  Registered by: | n/a

  Open an export dialog listing all printing plugins, prompt the user for their options, and print the layout.

  Available only with GUI HIDs: it's merely a graphical shorthand that in turn calls the export plugin for printing.

## PromptFor

  Syntax summary: | PromptFor([message[,default[,title]]])
  Help text: | Prompt for a string. Returns the string (or NULL on cancel)
  Registered by: | n/a

  UI-independent way of asking the user for a string. When GUI is available, it is a dialog box, else it's console input. Return value, unlike with other actions, is a string. The return value is NULL on cancel.

## ReloadScript

  Syntax summary: | ReloadScript(id)
  Help text: | Reload a fungw script
  Registered by: | script plugin

  id is the same that was specified for loadscript . If loading the new verison of the script fails, id is released (can be reused for a new LoadScript).

## rnd_toolbar_page

  Syntax summary: | rnd_toolbar_page(get|max|set|up|down, [pageidx])
  Help text: | For ringdove apps: page accessor .
  Registered by: | lib_hid_common plugin

  The toolbar may contain multiple pages toolbar buttons (icons), depending on how many toolbar buttons are defined by the menu file, the tools the and the value of config node plugins/lib_hid_common/toolbar/icons_per_page (that specifies how manu icons to put on a page). When there are multiple pages there is always one page of icons displayed and the page index can be modified by the up/down arrow buttons on the left side of the toolbar.

  This action is both an accessor for scripts and utility for keyboard/menu bindings. The first argument is a subcommand; some subcommands take a page index as the second argument. The subcommands are:

  get | Return the index of the currently active page (integer; for user scripting).
  max | Return the index of the last page (integer; for user scripting).
  set | Second argument is an integer page index between 0 and max, inclusive.
  up | Same effect as if the 'up' arrow button was pressed: select previous page, rolling over from page 0 to max page.
  down | Same effect as if the 'down' arrow button was pressed: select next page, rolling over from max page to page 0.

## ScriptCookie

  Syntax summary: | ScriptCookie()
  Help text: | Return a cookie specific to the current script instance during script initialization
  Registered by: | script plugin

  The script:

  - may call ScriptCookie() during script initialization and save the resulting cookie string
  - may use the cookie string to register to core application or librnd infrastructure that requires cookie, such as createmenu
  - can depend on the application to call any unregistering associated with this specific cookie atomatically after script unload ( preunload ).

  The function can not be called outside of script initialization. The cookie string can be used any time between script load and script unload.

## ScriptPersistency

  Syntax summary: | ScriptPersistency(read|remove)
  Help text: | Read or remove script persistency data savd on preunload
  Registered by: | script plugin

  When a script is unloaded, its action preunload is called. The return value is saved as script persistent data. When the script is loaded again later, it can use scriptpersistency ( read ) to read the data saved.

  scriptpersistency ( remove ) deletes the data from disk.

  Note: the data is per script id, not per script file name.

## Scroll

  Syntax summary: | Scroll(up|down|left|right, [pixels])
  Help text: | Scroll the viewport.
  Registered by: | lib_hid_common plugin

  Arguments:

  up|down|left|right | Specifies the direction to scroll
  pix | Optional. Specifies how many pixels to scroll by. If not specified: default pix is 100.

## SetGridOffs

  Syntax summary: | SetGridOffs(x_offs, y_offs)
  Help text: | Change grid offset (alignment) to x_offs and y_offs. Offsets should be specified with units.
  Registered by: | n/a

  Changes the grid offset to relative or absolute x_offs and y_offs. For non-zero values always use units, e.g. SetGrifOffs(0.5mm, 0.1mm).

  The final grid offset alues will be scaled down so they are always between 0 and the current grid size. For example with a 25 mil grid, a value of 7mil will be taken as 7mil offset, but a value of 27 mil will be taken as a 2mil offset.

  If an offset starts with + or -, it is taken as relative, which means it is added to the current offset value.

## SetUnits

  Syntax summary: | SetUnits(mm|mil)
  Help text: | Set the default measurement units.
  Registered by: | n/a

  mil | Sets the display units to mils (1/1000 inch).
  mm | Sets the display units to millimeters.

## Tool

  Syntax summary: | Tool(Arc|Arrow|Copy|InsertPoint|Line|Lock|Move|None|PasteBuffer) Tool(Poly|Rectangle|Remove|Rotate|Text|Thermal|Via) Tool(Press|Release|Cancel|Stroke) Tool(Save|Restore)
  Help text: | Change or use the tool mode.
  Registered by: | n/a

  Selects the tool or changes tool related global states.

  <app-specific-tool-name> | Select the indicated tool. Tool names depend on the application and plugins loaded. For example in pcb-rnd one of the valid tool names is Line .
  Press | Called when you press the mouse button, or move the mouse.
  Release | Called when you release the mouse button.
  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.
  Escape | Similar to Cancel but calling this action a second time will return to the Arrow tool.
  Stroke | If librnd 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.
  Save | Remembers the current tool.
  Restore | Restores the tool to the last saved tool.

## UnloadScript

  Syntax summary: | UnloadScript(id)
  Help text: | Unload a fungw script
  Registered by: | script plugin

  id is the same that was specified for loadscript . After the call id is released (can be reused for a new LoadScript).