camv-rnd actions (details)

layer

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

Change a layer property or layer ordering, depending on the argument:

Up or down moves the layer one slot up or down in layer ordering. Top or bottom moves the layer to the top or bottom in layer ordering. Layers are rendered from bottom to top: layers higher on the list will render over layers lower on the list. This matters especially if appearance/layer_alpha is 1 and layers are solid with no translucencly.

Del removes the currently selected layer.

getidx returns the index of the currently selected layer as an integer; getlen returns the number of layers as an integer. These are useful for user scripting.

setcolor and rename changes the color or name of the currently selected layer (new color or name supplied as a second argument).

all-visible and all-invisible changes visibility of all layers.

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.
board	The values are percentages of the board size. Thus, a move of 50,50 moves you halfway across the board.

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