# sch-rnd actions (details)

## FuncmapChange

  Syntax summary: | FuncmapChange(previous|next|remove, component, port) FuncmapChange(set, component, port, [newfunc]) FuncmapChange(setgrp, component, grpname)
  Help text: | Change the alternate function of a component-port. The setgrp command activates a group by setting all affected ports to that group's funcionality. All arguments are case-sensitive.
  Registered by: | funcmap

  Changes the funcmap/name attribute on one or more ports of a given component. The component (and port, when needed), needs to be named and is looked up in the abstract model (the project needs to be compiled). The actual change is always made in concrete terminal object(s) looked up from the abstract port objects. If multiple terminals are contributing to the port (source terminals), the change is done to the terminals that already have the funcmap/name attribute. If none of the source terminals have that attribute, the attribute is created in one of the source terminals randomly chosen.

  The first argument is the command to perform.

  If the command is previous or next , the selected function of the given port is moved one step back or forward on the function list for the port. The function list has the order of functions as they appear in the li:funcmap/ports section of the funcmap file (this differs from the column ordering in the tabular form, which is deduced from function grouping).

  If the command is set and the new function is specified as the 4th argument, the source terminal attribute is changed to that function. The added value of this command compared to the propset() action is that it looks up the terminal object to change and verifies whether the new function is available for the given port.

  The setgrp command modifies multiple terminals so that a whole function group is activated (by function group name).

## FuncmapPrintTable

  Syntax summary: | FuncmapPrintTable(component, [column])
  Help text: | Print a table of all alternative port functions for a component If column is specified, sort the table by the named column.
  Registered by: | funcmap

  Prints the function mapping of a component in the standard tabular form to the stdout. Each row is a port, each column is a function group. Cells are function names. The function that's active for a port is wrapped in [[]].

  If the optional second parameter is specified and is a valid column name, the table is sorted by that column.

## Quit

  Syntax summary: | Quit()
  Help text: | Quits sch-rnd after confirming.
  Registered by: | n/a

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

## RtreeList

  Syntax summary: | RtreeList[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

  Search all objects of the selected layer's named rtree on the current sheet and return a list of idpaths.

  The first argument is a layer name with an optional suffix. A layer name is the same as layer names printed by the GUI, e.g. "wire" or "hub & terminal". Suffix may be "-stroke" or "-fill"; when no suffix is appended, "-stroke" is assumed. All normal objects are in the stroke rtree; polygons with fill enabled are also in the fill rtree.

  If coordinates of a box is give, smaller coords first, the search is performed only within that box and any object that has overlapping bounding box (on the given layer) is returned. Otherwise the search is performed on the whole rtree, returning all objects on the layer.

## Zoom

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

  Changes the zoom (magnification) of the view of the sheet. If no arguments are passed, the view is scaled such that the sheet 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 sheet extents.
  +factor | Values greater than 1.0 cause the sheet to be drawn smaller; more of the sheet will be visible. Values between 0.0 and 1.0 cause the sheet to be drawn bigger; less of the sheet will be visible.
  -factor | Values greater than 1.0 cause the sheet to be drawn bigger; less of the sheet will be visible. Values between 0.0 and 1.0 cause the sheet to be drawn smaller; more of the sheet 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 sheet space coordinates)
  selected | Zoom and pan so that all selected 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).

## 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).