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:

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:

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

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:

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