neingeist
/
arduinisten
Archived
1
0
Fork 0
Code Releases Activity
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
This repo is archived. You can view files and clone it, but cannot push or open issues/pull-requests.
master
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '157fd6f1a1'
${ noResults }
arduinisten/eagle-5.7.0/bin/eagle_en.htm

16732 lines
642 KiB
HTML
Raw Blame History

<html>
<head>
<title>EAGLE Help Version 5.7.0</title>
<style type="text/css"><!-- h1 { background-color: #CCCCCC; color: #0050B0; } pre { background-color: #EEEEEE; } mb { font-weight: bold; font-family: courier; background-color: #EEEEEE; }--></style>
</head>
<body>
<table width=100% cellspacing=0 border=0><tr>
<td align=left>EAGLE Help Version 5.7.0</td>
<td align=right><font size=-1>
<i>Copyright &copy; 2010 CadSoft Computer GmbH</i>
</font></td></tr></table>
<h1>Index</h1>
<ul>
<li><a href=#1>General Help</a>
<li><a href=#2>Configuring EAGLE</a>
<li><a href=#3>Command Line Options</a>
<li><a href=#4>Quick Introduction</a>
<ul>
<li><a href=#5>Control Panel and Editor Windows</a>
<li><a href=#6>Entering Parameters and Values</a>
<li><a href=#7>Drawing a Schematic</a>
<li><a href=#8>Checking the Schematic</a>
<li><a href=#9>Generating a Board from a Schematic</a>
<li><a href=#10>Checking the Layout</a>
<li><a href=#11>Creating a Library Device</a>
</ul>
<li><a href=#12>Control Panel</a>
<ul>
<li><a href=#13>Context Menus</a>
<li><a href=#14>Directories</a>
<li><a href=#15>Backup</a>
<li><a href=#16>User Interface</a>
<li><a href=#17>Window positions</a>
<li><a href=#18>Check for Update</a>
</ul>
<li><a href=#19>Keyboard and Mouse</a>
<ul>
<li><a href=#20>Selecting objects in dense areas</a>
</ul>
<li><a href=#21>Editor Windows</a>
<ul>
<li><a href=#22>Library Editor</a>
<ul>
<li><a href=#23>Edit Library Object</a>
</ul>
<li><a href=#24>Board Editor</a>
<li><a href=#25>Schematic Editor</a>
<li><a href=#26>Text Editor</a>
</ul>
<li><a href=#27>Editor Commands</a>
<ul>
<li><a href=#28>Command Syntax</a>
<li><a href=#29>ADD</a>
<li><a href=#30>ARC</a>
<li><a href=#31>ASSIGN</a>
<li><a href=#32>ATTRIBUTE</a>
<li><a href=#33>AUTO</a>
<li><a href=#34>BOARD</a>
<li><a href=#35>BUS</a>
<li><a href=#36>CHANGE</a>
<li><a href=#37>CIRCLE</a>
<li><a href=#38>CLASS</a>
<li><a href=#39>CLOSE</a>
<li><a href=#40>CONNECT</a>
<li><a href=#41>COPY</a>
<li><a href=#42>CUT</a>
<li><a href=#43>DELETE</a>
<li><a href=#44>DESCRIPTION</a>
<li><a href=#45>DISPLAY</a>
<li><a href=#46>DRC</a>
<li><a href=#47>EDIT</a>
<li><a href=#48>ERC</a>
<li><a href=#49>ERRORS</a>
<li><a href=#50>EXPORT</a>
<li><a href=#51>FRAME</a>
<li><a href=#52>GATESWAP</a>
<li><a href=#53>GRID</a>
<li><a href=#54>GROUP</a>
<li><a href=#55>HELP</a>
<li><a href=#56>HOLE</a>
<li><a href=#57>INFO</a>
<li><a href=#58>INVOKE</a>
<li><a href=#59>JUNCTION</a>
<li><a href=#60>LABEL</a>
<li><a href=#61>LAYER</a>
<li><a href=#62>LOCK</a>
<li><a href=#63>MARK</a>
<li><a href=#64>MENU</a>
<li><a href=#65>MIRROR</a>
<li><a href=#66>MITER</a>
<li><a href=#67>MOVE</a>
<li><a href=#68>NAME</a>
<li><a href=#69>NET</a>
<li><a href=#70>OPEN</a>
<li><a href=#71>OPTIMIZE</a>
<li><a href=#72>PACKAGE</a>
<li><a href=#73>PAD</a>
<li><a href=#74>PASTE</a>
<li><a href=#75>PIN</a>
<li><a href=#76>PINSWAP</a>
<li><a href=#77>POLYGON</a>
<li><a href=#78>PREFIX</a>
<li><a href=#79>PRINT</a>
<li><a href=#80>QUIT</a>
<li><a href=#81>RATSNEST</a>
<li><a href=#82>RECT</a>
<li><a href=#83>REDO</a>
<li><a href=#84>REMOVE</a>
<li><a href=#85>RENAME</a>
<li><a href=#86>REPLACE</a>
<li><a href=#87>RIPUP</a>
<li><a href=#88>ROTATE</a>
<li><a href=#89>ROUTE</a>
<li><a href=#90>RUN</a>
<li><a href=#91>SCRIPT</a>
<li><a href=#92>SET</a>
<li><a href=#93>SHOW</a>
<li><a href=#94>SIGNAL</a>
<li><a href=#95>SMASH</a>
<li><a href=#96>SMD</a>
<li><a href=#97>SPLIT</a>
<li><a href=#98>TECHNOLOGY</a>
<li><a href=#99>TEXT</a>
<li><a href=#100>UNDO</a>
<li><a href=#101>UPDATE</a>
<li><a href=#102>USE</a>
<li><a href=#103>VALUE</a>
<li><a href=#104>VIA</a>
<li><a href=#105>WINDOW</a>
<li><a href=#106>WIRE</a>
<li><a href=#107>WRITE</a>
</ul>
<li><a href=#108>Generating Output</a>
<ul>
<li><a href=#109>Printing</a>
<ul>
<li><a href=#110>Printing a Drawing</a>
<li><a href=#111>Printing a Text</a>
<li><a href=#112>Printer Page Setup</a>
</ul>
<li><a href=#113>CAM Processor</a>
<ul>
<li><a href=#114>Main CAM Menu</a>
<li><a href=#115>CAM Processor Job</a>
<li><a href=#116>Output Device</a>
<ul>
<li><a href=#117>Device Parameters</a>
<ul>
<li><a href=#118>Aperture Wheel File</a>
<li><a href=#119>Aperture Emulation</a>
<li><a href=#120>Aperture Tolerances</a>
<li><a href=#121>Drill Rack File</a>
<li><a href=#122>Drill Tolerances</a>
<li><a href=#123>Offset</a>
<li><a href=#124>Printable Area</a>
<li><a href=#125>Pen Data</a>
</ul>
<li><a href=#126>Defining Your Own Device Driver</a>
</ul>
<li><a href=#127>Output File</a>
<li><a href=#128>Flag Options</a>
<li><a href=#129>Layers and Colors</a>
</ul>
<li><a href=#130>Outlines data</a>
</ul>
<li><a href=#131>Autorouter</a>
<li><a href=#132>Design Checks</a>
<ul>
<li><a href=#133>Design Rules</a>
</ul>
<li><a href=#134>Cross-references</a>
<ul>
<li><a href=#135>Cross-reference labels</a>
<li><a href=#136>Part cross-references</a>
<li><a href=#137>Contact cross-references</a>
</ul>
<li><a href=#138>User Language</a>
<ul>
<li><a href=#139>Writing a ULP</a>
<li><a href=#140>Executing a ULP</a>
<li><a href=#141>Syntax</a>
<ul>
<li><a href=#142>Whitespace</a>
<li><a href=#143>Comments</a>
<li><a href=#144>Directives</a>
<ul>
<li><a href=#145>#include</a>
<li><a href=#146>#require</a>
<li><a href=#147>#usage</a>
</ul>
<li><a href=#148>Keywords</a>
<li><a href=#149>Identifiers</a>
<li><a href=#150>Constants</a>
<ul>
<li><a href=#151>Character Constants</a>
<li><a href=#152>Integer Constants</a>
<li><a href=#153>Real Constants</a>
<li><a href=#154>String Constants</a>
<li><a href=#155>Escape Sequences</a>
</ul>
<li><a href=#156>Punctuators</a>
<ul>
<li><a href=#157>Brackets</a>
<li><a href=#158>Parentheses</a>
<li><a href=#159>Braces</a>
<li><a href=#160>Comma</a>
<li><a href=#161>Semicolon</a>
<li><a href=#162>Colon</a>
<li><a href=#163>Equal Sign</a>
</ul>
</ul>
<li><a href=#164>Data Types</a>
<ul>
<li><a href=#165>char</a>
<li><a href=#166>int</a>
<li><a href=#167>real</a>
<li><a href=#168>string</a>
<li><a href=#169>Type Conversions</a>
<li><a href=#170>Typecast</a>
</ul>
<li><a href=#171>Object Types</a>
<ul>
<li><a href=#172>UL_ARC</a>
<li><a href=#173>UL_AREA</a>
<li><a href=#174>UL_ATTRIBUTE</a>
<li><a href=#175>UL_BOARD</a>
<li><a href=#176>UL_BUS</a>
<li><a href=#177>UL_CIRCLE</a>
<li><a href=#178>UL_CLASS</a>
<li><a href=#179>UL_CONTACT</a>
<li><a href=#180>UL_CONTACTREF</a>
<li><a href=#181>UL_DEVICE</a>
<li><a href=#182>UL_DEVICESET</a>
<li><a href=#183>UL_ELEMENT</a>
<li><a href=#184>UL_FRAME</a>
<li><a href=#185>UL_GATE</a>
<li><a href=#186>UL_GRID</a>
<li><a href=#187>UL_HOLE</a>
<li><a href=#188>UL_INSTANCE</a>
<li><a href=#189>UL_JUNCTION</a>
<li><a href=#190>UL_LABEL</a>
<li><a href=#191>UL_LAYER</a>
<li><a href=#192>UL_LIBRARY</a>
<li><a href=#193>UL_NET</a>
<li><a href=#194>UL_PACKAGE</a>
<li><a href=#195>UL_PAD</a>
<li><a href=#196>UL_PART</a>
<li><a href=#197>UL_PIN</a>
<li><a href=#198>UL_PINREF</a>
<li><a href=#199>UL_POLYGON</a>
<li><a href=#200>UL_RECTANGLE</a>
<li><a href=#201>UL_SCHEMATIC</a>
<li><a href=#202>UL_SEGMENT</a>
<li><a href=#203>UL_SHEET</a>
<li><a href=#204>UL_SIGNAL</a>
<li><a href=#205>UL_SMD</a>
<li><a href=#206>UL_SYMBOL</a>
<li><a href=#207>UL_TEXT</a>
<li><a href=#208>UL_VIA</a>
<li><a href=#209>UL_WIRE</a>
</ul>
<li><a href=#210>Definitions</a>
<ul>
<li><a href=#211>Constant Definitions</a>
<li><a href=#212>Variable Definitions</a>
<li><a href=#213>Function Definitions</a>
</ul>
<li><a href=#214>Operators</a>
<ul>
<li><a href=#215>Bitwise Operators</a>
<li><a href=#216>Logical Operators</a>
<li><a href=#217>Comparison Operators</a>
<li><a href=#218>Evaluation Operators</a>
<li><a href=#219>Arithmetic Operators</a>
<li><a href=#220>String Operators</a>
</ul>
<li><a href=#221>Expressions</a>
<ul>
<li><a href=#222>Arithmetic Expression</a>
<li><a href=#223>Assignment Expression</a>
<li><a href=#224>String Expression</a>
<li><a href=#225>Comma Expression</a>
<li><a href=#226>Conditional Expression</a>
<li><a href=#227>Function Call</a>
</ul>
<li><a href=#228>Statements</a>
<ul>
<li><a href=#229>Compound Statement</a>
<li><a href=#230>Expression Statement</a>
<li><a href=#231>Control Statements</a>
<ul>
<li><a href=#232>break</a>
<li><a href=#233>continue</a>
<li><a href=#234>do...while</a>
<li><a href=#235>for</a>
<li><a href=#236>if...else</a>
<li><a href=#237>return</a>
<li><a href=#238>switch</a>
<li><a href=#239>while</a>
</ul>
</ul>
<li><a href=#240>Builtins</a>
<ul>
<li><a href=#241>Builtin Constants</a>
<li><a href=#242>Builtin Variables</a>
<li><a href=#243>Builtin Functions</a>
<ul>
<li><a href=#244>Character Functions</a>
<ul>
<li><a href=#245>is...()</a>
<li><a href=#246>to...()</a>
</ul>
<li><a href=#247>File Handling Functions</a>
<ul>
<li><a href=#248>fileerror()</a>
<li><a href=#249>fileglob()</a>
<li><a href=#250>Filename Functions</a>
<li><a href=#251>Filedata Functions</a>
<li><a href=#252>File Input Functions</a>
<ul>
<li><a href=#253>fileread()</a>
</ul>
</ul>
<li><a href=#254>Mathematical Functions</a>
<ul>
<li><a href=#255>Absolute, Maximum and Minimum Functions</a>
<li><a href=#256>Rounding Functions</a>
<li><a href=#257>Trigonometric Functions</a>
<li><a href=#258>Exponential Functions</a>
</ul>
<li><a href=#259>Miscellaneous Functions</a>
<ul>
<li><a href=#260>exit()</a>
<li><a href=#261>language()</a>
<li><a href=#262>lookup()</a>
<li><a href=#263>palette()</a>
<li><a href=#264>sort()</a>
<li><a href=#265>status()</a>
<li><a href=#266>system()</a>
<li><a href=#267>Unit Conversions</a>
</ul>
<li><a href=#268>Printing Functions</a>
<ul>
<li><a href=#269>printf()</a>
<li><a href=#270>sprintf()</a>
</ul>
<li><a href=#271>String Functions</a>
<ul>
<li><a href=#272>strchr()</a>
<li><a href=#273>strjoin()</a>
<li><a href=#274>strlen()</a>
<li><a href=#275>strlwr()</a>
<li><a href=#276>strrchr()</a>
<li><a href=#277>strrstr()</a>
<li><a href=#278>strsplit()</a>
<li><a href=#279>strstr()</a>
<li><a href=#280>strsub()</a>
<li><a href=#281>strtod()</a>
<li><a href=#282>strtol()</a>
<li><a href=#283>strupr()</a>
<li><a href=#284>strxstr()</a>
</ul>
<li><a href=#285>Time Functions</a>
<ul>
<li><a href=#286>time()</a>
<li><a href=#287>timems()</a>
<li><a href=#288>Time Conversions</a>
</ul>
<li><a href=#289>Object Functions</a>
<ul>
<li><a href=#290>clrgroup()</a>
<li><a href=#291>ingroup()</a>
<li><a href=#292>setgroup()</a>
</ul>
</ul>
<li><a href=#293>Builtin Statements</a>
<ul>
<li><a href=#294>board()</a>
<li><a href=#295>deviceset()</a>
<li><a href=#296>library()</a>
<li><a href=#297>output()</a>
<li><a href=#298>package()</a>
<li><a href=#299>schematic()</a>
<li><a href=#300>sheet()</a>
<li><a href=#301>symbol()</a>
</ul>
</ul>
<li><a href=#302>Dialogs</a>
<ul>
<li><a href=#303>Predefined Dialogs</a>
<ul>
<li><a href=#304>dlgDirectory()</a>
<li><a href=#305>dlgFileOpen(), dlgFileSave()</a>
<li><a href=#306>dlgMessageBox()</a>
</ul>
<li><a href=#307>Dialog Objects</a>
<ul>
<li><a href=#308>dlgCell</a>
<li><a href=#309>dlgCheckBox</a>
<li><a href=#310>dlgComboBox</a>
<li><a href=#311>dlgDialog</a>
<li><a href=#312>dlgGridLayout</a>
<li><a href=#313>dlgGroup</a>
<li><a href=#314>dlgHBoxLayout</a>
<li><a href=#315>dlgIntEdit</a>
<li><a href=#316>dlgLabel</a>
<li><a href=#317>dlgListBox</a>
<li><a href=#318>dlgListView</a>
<li><a href=#319>dlgPushButton</a>
<li><a href=#320>dlgRadioButton</a>
<li><a href=#321>dlgRealEdit</a>
<li><a href=#322>dlgSpacing</a>
<li><a href=#323>dlgSpinBox</a>
<li><a href=#324>dlgStretch</a>
<li><a href=#325>dlgStringEdit</a>
<li><a href=#326>dlgTabPage</a>
<li><a href=#327>dlgTabWidget</a>
<li><a href=#328>dlgTextEdit</a>
<li><a href=#329>dlgTextView</a>
<li><a href=#330>dlgVBoxLayout</a>
</ul>
<li><a href=#331>Layout Information</a>
<li><a href=#332>Dialog Functions</a>
<ul>
<li><a href=#333>dlgAccept()</a>
<li><a href=#334>dlgRedisplay()</a>
<li><a href=#335>dlgReset()</a>
<li><a href=#336>dlgReject()</a>
</ul>
<li><a href=#337>Escape Character</a>
<li><a href=#338>A Complete Example</a>
</ul>
<li><a href=#339>Supported HTML tags</a>
</ul>
<li><a href=#340>Automatic Backup</a>
<li><a href=#341>Forward&amp;Back Annotation</a>
<ul>
<li><a href=#342>Consistency Check</a>
<li><a href=#343>Limitations</a>
</ul>
<li><a href=#344>Technical Support</a>
<li><a href=#345>License</a>
<ul>
<li><a href=#346>EAGLE License</a>
<li><a href=#347>EAGLE Editions</a>
</ul>
</ul>
<a name=1>
<h1>General Help</h1>
While inside a <a href=#24>board</a>,
<a href=#25>schematic</a>, or
<a href=#22>library</a> editor window,
pressing F1 or entering the command <tt>HELP</tt>
will open the help page for the currently active command.
<p>
You can also display an editor command's help page by entering
<pre>
HELP command
</pre>
replacing "command" with, e.g., <tt>MOVE</tt>, which would display the help
page for the MOVE command.
<p>
Anywhere else, pressing the F1 key will bring up a context sensitive
help page for the menu, dialog or action that is currently active.
<p>
For detailed information on how to get started with EAGLE please read the
following help pages:
<ul>
<li><a href=#4>Quick Introduction</a>
<li><a href=#2>Configuring EAGLE</a>
<li><a href=#3>Command Line Options</a>
<li><a href=#12>Control Panel</a>
</ul>
<a name=2>
<h1>Configuring EAGLE</h1>
Global EAGLE parameters can be adjusted in the
<a href=#12>Control Panel</a>.
<p>
The following editor commands can be used to customize the way EAGLE works.
They can be given either directly from an editor window's command line,
or in the <a href=#91>eagle.scr</a> file.
<h2>User Interface</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Command menu </td><td width=20><td><a href=#64>MENU</a> command..;</td></tr>
<tr><td>Assign keys </td><td width=20><td><a href=#31>ASSIGN</a> function_key command..;</td></tr>
<tr><td>Snap function </td><td width=20><td><a href=#92>SET</a> SNAP_LENGTH number;</td></tr>
<tr><td> </td><td width=20><td><a href=#92>SET</a> CATCH_FACTOR value;</td></tr>
<tr><td> </td><td width=20><td><a href=#92>SET</a> SELECT_FACTOR value;</td></tr>
<tr><td>Content of menus </td><td width=20><td><a href=#92>SET</a> USED_LAYERS name | number;</td></tr>
<tr><td> </td><td width=20><td><a href=#92>SET</a> WIDTH_MENU value..;</td></tr>
<tr><td> </td><td width=20><td><a href=#92>SET</a> DIAMETER_MENU value..;</td></tr>
<tr><td> </td><td width=20><td><a href=#92>SET</a> DRILL_MENU value..;</td></tr>
<tr><td> </td><td width=20><td><a href=#92>SET</a> SMD_MENU value..;</td></tr>
<tr><td> </td><td width=20><td><a href=#92>SET</a> SIZE_MENU value..;</td></tr>
<tr><td> </td><td width=20><td><a href=#92>SET</a> ISOLATE_MENU value..;</td></tr>
<tr><td> </td><td width=20><td><a href=#92>SET</a> SPACING_MENU value..;</td></tr>
<tr><td> </td><td width=20><td><a href=#92>SET</a> MITER_MENU value..;</td></tr>
<tr><td>Wire bend </td><td width=20><td><a href=#92>SET</a> WIRE_BEND bend_nr;</td></tr>
<tr><td>Beep on/off </td><td width=20><td><a href=#92>SET</a> BEEP OFF | ON;</td></tr>
</table>
<h2>Screen Display</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Color for grid lines </td><td width=20><td><a href=#92>SET</a> COLOR_GRID color;</td></tr>
<tr><td>Color for layer </td><td width=20><td><a href=#92>SET</a> COLOR_LAYER layer color;</td></tr>
<tr><td>Fill style for layer </td><td width=20><td><a href=#92>SET</a> FILL_LAYER layer fill;</td></tr>
<tr><td>Grid parameter </td><td width=20><td><a href=#92>SET</a> MIN_GRID_SIZE pixels;</td></tr>
<tr><td>Min. text size displayed </td><td width=20><td><a href=#92>SET</a> MIN_TEXT_SIZE size;</td></tr>
<tr><td>Display of net lines </td><td width=20><td><a href=#92>SET</a> NET_WIRE_WIDTH width;</td></tr>
<tr><td>Display of pads </td><td width=20><td><a href=#92>SET</a> DISPLAY_MODE REAL | NODRILL;</td></tr>
<tr><td> </td><td width=20><td><a href=#92>SET</a> PAD_NAMES OFF | ON;</td></tr>
<tr><td>Display of bus lines </td><td width=20><td><a href=#92>SET</a> BUS_WIRE_WIDTH width;</td></tr>
<tr><td>DRC fill style </td><td width=20><td><a href=#92>SET</a> DRC_FILL fill_name;</td></tr>
<tr><td>Polygon processing </td><td width=20><td><a href=#92>SET</a> POLYGON_RATSNEST OFF | ON;</td></tr>
<tr><td>Vector font </td><td width=20><td><a href=#92>SET</a> VECTOR_FONT OFF | ON;</td></tr>
</table>
<h2>Mode Parameters</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Package check </td><td width=20><td><a href=#92>SET</a> CHECK_CONNECTS OFF | ON;</td></tr>
<tr><td>Grid parameters </td><td width=20><td><a href=#53>GRID</a> options;</td></tr>
<tr><td>Replace mode </td><td width=20><td><a href=#92>SET</a> REPLACE_SAME NAMES | COORDS;</td></tr>
<tr><td>UNDO Buffer </td><td width=20><td><a href=#92>SET</a> UNDO_LOG OFF | ON;</td></tr>
<tr><td>Wire Optimizing </td><td width=20><td><a href=#92>SET</a> OPTIMIZING OFF | ON;</td></tr>
<tr><td>Net wire termination </td><td width=20><td><a href=#92>SET</a> AUTO_END_NET OFF | ON;</td></tr>
<tr><td>Automatic junctions </td><td width=20><td><a href=#92>SET</a> AUTO_JUNCTION OFF | ON;</td></tr>
</table>
<h2>Presettings</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Pad shape </td><td width=20><td><a href=#36>CHANGE</a> SHAPE shape;</td></tr>
<tr><td>Wire width </td><td width=20><td><a href=#36>CHANGE</a> WIDTH value;</td></tr>
<tr><td>Pad/via diameter </td><td width=20><td><a href=#36>CHANGE</a> DIAMETER diameter;</td></tr>
<tr><td>Pad/via/hole drill diam. </td><td width=20><td><a href=#36>CHANGE</a> DRILL value;</td></tr>
<tr><td>Smd size </td><td width=20><td><a href=#36>CHANGE</a> SMD width height;</td></tr>
<tr><td>Text height </td><td width=20><td><a href=#36>CHANGE</a> SIZE value;</td></tr>
<tr><td>Text line width </td><td width=20><td><a href=#36>CHANGE</a> RATIO ratio;</td></tr>
<tr><td>Text font </td><td width=20><td><a href=#36>CHANGE</a> FONT font;</td></tr>
<tr><td>Polygon parameter </td><td width=20><td><a href=#36>CHANGE</a> THERMALS OFF | ON;</td></tr>
<tr><td>Polygon parameter </td><td width=20><td><a href=#36>CHANGE</a> ORPHANS OFF | ON;</td></tr>
<tr><td>Polygon parameter </td><td width=20><td><a href=#36>CHANGE</a> ISOLATE distance;</td></tr>
<tr><td>Polygon parameter </td><td width=20><td><a href=#36>CHANGE</a> POUR SOLID | HATCH;</td></tr>
<tr><td>Polygon parameter </td><td width=20><td><a href=#36>CHANGE</a> RANK value;</td></tr>
<tr><td>Polygon parameter </td><td width=20><td><a href=#36>CHANGE</a> SPACING distance;</td></tr>
</table>
<a name=3>
<h1>Command Line Options</h1>
You can call up EAGLE with command line parameters. Use the following format:
<pre>
eagle [ options [ filename [ layer ] ] ]
</pre>
<h2>Options</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>-Cxxx</tt></td> <td width=20><td>execute the given Command</td></tr>
<tr><td><tt>-Dxxx</tt></td> <td width=20><td>Draw tolerance (0.1 = 10%)</td></tr>
<tr><td><tt>-Exxx</tt></td> <td width=20><td>Drill tolerance (0.1 = 10%)</td></tr>
<tr><td><tt>-Fxxx</tt></td> <td width=20><td>Flash tolerance (0.1 = 10%)</td></tr>
<tr><td><tt>-N-</tt></td> <td width=20><td>no command line prompts</td></tr>
<tr><td><tt>-O+</tt></td> <td width=20><td>Optimize pen movement</td></tr>
<tr><td><tt>-Pxxx</tt></td> <td width=20><td>plotter Pen (layer=pen)</td></tr>
<tr><td><tt>-Rxxx</tt></td> <td width=20><td>drill Rack file</td></tr>
<tr><td><tt>-Sxxx</tt></td> <td width=20><td>Scriptfile</td></tr>
<tr><td><tt>-Wxxx</tt></td> <td width=20><td>aperture Wheel file</td></tr>
<tr><td><tt>-X-</tt></td> <td width=20><td>eXecute CAM Processor</td></tr>
<tr><td><tt>-a-</tt></td> <td width=20><td>emulate Annulus</td></tr>
<tr><td><tt>-c+</tt></td> <td width=20><td>positive Coordinates</td></tr>
<tr><td><tt>-dxxx</tt></td> <td width=20><td>Device (-d? for list)</td></tr>
<tr><td><tt>-e-</tt></td> <td width=20><td>Emulate apertures</td></tr>
<tr><td><tt>-f+</tt></td> <td width=20><td>Fill pads</td></tr>
<tr><td><tt>-hxxx</tt></td> <td width=20><td>page Height (inch)</td></tr>
<tr><td><tt>-m-</tt></td> <td width=20><td>Mirror output</td></tr>
<tr><td><tt>-oxxx</tt></td> <td width=20><td>Output filename</td></tr>
<tr><td><tt>-pxxx</tt></td> <td width=20><td>Pen diameter (mm)</td></tr>
<tr><td><tt>-q-</tt></td> <td width=20><td>Quick plot</td></tr>
<tr><td><tt>-r-</tt></td> <td width=20><td>Rotate output 90 degrees</td></tr>
<tr><td><tt>-sxxx</tt></td> <td width=20><td>Scale factor</td></tr>
<tr><td><tt>-t-</tt></td> <td width=20><td>emulate Thermal</td></tr>
<tr><td><tt>-u-</tt></td> <td width=20><td>output Upside down</td></tr>
<tr><td><tt>-vxxx</tt></td> <td width=20><td>pen Velocity</td></tr>
<tr><td><tt>-wxxx</tt></td> <td width=20><td>page Width (inch)</td></tr>
<tr><td><tt>-xxxx</tt></td> <td width=20><td>offset X (inch)</td></tr>
<tr><td><tt>-yxxx</tt></td> <td width=20><td>offset Y (inch)</td></tr>
</table>
<p>
where <tt>xxx</tt> means that further data, e.g. a file name or a decimal number
needs to be appended to the option character (without space or separated by a space),
as in
<pre>
-Wmywheel.whl
-W mywheel.whl
-e Aperture emulation on
-e+ dto.
-e- Aperture emulation off
</pre>
For flag options, a <tt>'-'</tt> means that the option is off by default, while
<tt>'+'</tt> means it is on by default.
<p>
Flag options (e.g. <tt>-e</tt>) can be used without repeating the <tt>'-'</tt> character:
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>-eatm</tt></td> <td width=20><td>Aperture emulation on, annulus and thermal emulation on, mirror output</td></tr>
<tr><td><tt>-ea-t+</tt></td> <td width=20><td>Aperture emulation on, annulus emulation <b>off</b>, thermal emulation <b>on</b></td></tr>
</table>
<h2>Defining Tolerance Values</h2>
Without <tt>'+'</tt> or <tt>'-'</tt> sign, a tolerance value applies to both directions:
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>-D0.10</tt></td> <td width=20><td>adjusts the draw tolerance to &plusmn;10%</td></tr>
<tr><td><tt>-D+0.1 -D-0.05</tt></td> <td width=20><td>adjusts the draw toleranceto +10% and -5%</td></tr>
</table>
<h2>Executing commands</h2>
If a command is given with the <tt>'-C'</tt> option, as in
<pre>
eagle -C "window (1 1) (2 2);" myboard.brd
</pre>
EAGLE will load the given file and execute the command as if it had been
typed into the editor window's command line.
<p>
The following conditions apply for the <tt>'-C'</tt> option:
<ul>
<li>A file name (board, schematic or library) must be given, so that an editor
window will be opened in which the command can be executed. That file doesn't
necessarily need to exist.
<li>The <tt>eagle.scr</tt> file will not be executed automatically.
<li>The option <tt>'-s'</tt> will be ignored.
<li>The user settings will not be written back to the <tt>eaglerc</tt> file.
<li>Any project that has been open when EAGLE was left the last time will not be opened.
<li>The command can be a single command, or a sequence of commands delimited by
semicolons.
</ul>
To run EAGLE without automatically executing the <tt>eagle.scr</tt> file or loading
a project, the command string can be empty, as in
<pre>
eagle -C ""
</pre>
Note that in this special case there must be a blank between the option character
and the quotes, so that the program will see the explicitly empty string. There
also doesn't have to be a file name here, because no command will actually be
executed.
<h2>Filename</h2>
If the given filename is <tt>eagle.epf</tt> (optionally preceded by a directory name),
EAGLE will load that Project File. Otherwise, if no file extension is given,
it defaults to <tt>.brd</tt>, to load a board file.
<a name=4>
<h1>Quick Introduction</h1>
For a quick start you should know more about the following topics:
<ul>
<li><a href=#5>Control Panel and Editor Windows</a>
<li><a href=#28>Using Editor Commands</a>
<li><a href=#6>Entering Parameters and Values</a>
<li><a href=#7>Drawing a Schematic</a>
<li><a href=#8>Checking the Schematic</a>
<li><a href=#9>Generating a Board from a Schematic</a>
<li><a href=#10>Checking the Layout</a>
<li><a href=#11>Creating a Library Device</a>
<li><a href=#131>Using the Autorouter</a>
<li><a href=#109>Using the System Printer</a>
<li><a href=#113>Using the CAM Processor</a>
</ul>
In case of problems please contact our
free <a href=#344>Technical Support</a>.
<a name=5>
<h1>Control Panel and Editor Windows</h1>
From the <a href=#12>Control Panel</a> you can open schematic,
board, or library editor windows by using the File menu or double clicking
an icon.
<a name=6>
<h1>Entering Parameters and Values</h1>
Parameters and values can be entered in the EAGLE command line
or, more conveniently, in the Parameter Toolbars which appear when a
command is activated. As this is quite self-explanatory, the help text
does not explicitly mention this option at other locations.
<p>
Wherever coordinates or sizes (like width, diameter etc.) can be entered, they may
be given with units, as in 50mil or 0.8mm. If no unit is given, the current grid unit is used.
<a name=7>
<h1>Drawing a Schematic</h1>
<h2>Create a Schematic File</h2>
Use File/New and Save as to create a schematic with a name of your
choice.
<h2>Load a Drawing Frame</h2>
Load library FRAMES with <a href=#102>USE</a> and place a frame of your choice with <a href=#29>ADD</a>.
<h2>Place Symbols</h2>
Load appropriate libraries with <a href=#102>USE</a> and place symbols (see <a href=#29>ADD</a>, <a href=#67>MOVE</a>,
<a href=#43>DELETE</a>, <a href=#88>ROTATE</a>, <a href=#68>NAME</a>, <a href=#103>VALUE</a>). Where a particular component is not
available, define a new one with the library editor.
<h2>Draw Bus Connections</h2>
Using the <a href=#35>BUS</a> command, draw bus connections. You can <a href=#68>NAME</a> a bus in
such a way that you can drag nets out of the bus which are named
accordingly.
<h2>Draw Net Connections</h2>
Using the <a href=#69>NET</a> command, connect up the pins of the various elements on
the drawing. Intersecting nets may be made into connections with the
<a href=#59>JUNCTION</a> command.
<a name=8>
<h1>Checking the Schematic</h1>
Carry out an electrical rule check (<a href=#48>ERC</a>) to look for open pins, etc.,
and use the messages generated to correct any errors. Use the <a href=#93>SHOW</a>
command to follow complete nets across the screen. Use the <a href=#50>EXPORT</a> command
to generate a netlist, pinlist, or partlist if necessary.
<a name=9>
<h1>Generating a Board from a Schematic</h1>
By using the <a href=#34>BOARD</a> command or clicking the Switch-to-Board icon you
can generate a board from the loaded schematic (if there is no board
with the same name yet).
<p>
All the components, together with their connections drawn as airwires,
appear beside a blank board ready for placing. Power pins are
automatically connected to the appropriate supply (if not connected by
a net on the schematic).
<p>
The board is linked to the schematic via <a href=#341>Forward&amp;Back Annotation</a>.
This mechanism makes sure that schematic and board are consistent.
When editing a drawing, board and schematic must be loaded to keep
Forward&amp;Back Annotation active.
<h2>Set Board Outlines and Place Components</h2>
The board outlines can be adjusted with the <a href=#67>MOVE</a> and <a href=#97>SPLIT</a>
commands as appropriate before moving each package on the board. Once
all packages have been placed, the <a href=#81>RATSNEST</a> command is used to
optimize airwires.
<h2>Define Restricted Areas</h2>
If required, restricted areas for the Autorouter can be defined as
<a href=#82>RECT</a>angles, <a href=#77>POLYGON</a>s, or <a href=#37>CIRCLE</a>s on the tRestrict, bRestrict, or
vRestrict layers. Note: areas enclosed by wires drawn on the Dimension
layer are borders for the Autorouter, too.
<h2>Routing</h2>
Airwires are now converted into tracks with the aid of the <a href=#89>ROUTE</a>
command. This function can also be performed automatically by the
<a href=#33>Autorouter</a>, when available.
<a name=10>
<h1>Checking the Layout</h1>
Check the layout (<a href=#46>DRC</a>) and correct the errors (<a href=#49>ERRORS</a>). Generate
net, part, or pin list if necessary(<a href=#50>EXPORT</a>).
<a name=11>
<h1>Creating a Library Device</h1>
Creating a new component part in a library has three steps. You must
follow these steps as they build upon each other.
<p>
To start, open a library. Use the File menu Open or New command (not
the USE command).
<h2>Create a Package</h2>
Packages are the part of the device that are added to a board.
<p>
Click the Edit Package icon and edit a new package by typing its
name in the New field of the dialog box.
<p>
Set the proper distance <a href=#53>GRID</a>.
<p>
<a href=#68>NAME</a> and place <a href=#73>PAD</a>s properly.
<p>
Add texts &gt;NAME and &gt;VALUE with the <a href=#99>TEXT</a> command (show actual name and
value in the board) and draw package outlines (<a href=#106>WIRE</a> command) in the
proper layers.
<h2>Create a Symbol</h2>
Symbols are the part of the device that are added to a schematic.
<p>
Click the Edit Symbol icon and edit a new symbol by typing its
name in the New field of the dialog box.
<p>
Place and name pins with the commands <a href=#75>PIN</a> and <a href=#68>NAME</a> and provide pin
parameters (<a href=#36>CHANGE</a>).
<p>
Add texts &gt;NAME and &gt;VALUE with the <a href=#99>TEXT</a> command (show actual name and
value in the schematic) and draw symbol outlines (<a href=#106>WIRE</a> command) in the
proper layers.
<h2>Create the Device</h2>
Devices are the "master" part of a component and use both a package
and one or more symbols.
<p>
Click the Edit Device icon and edit a new device by typing its
name in the New field of the dialog box.
<p>
Assign the package with the <a href=#72>PACKAGE</a> command.
<p>
Add the gate(s) with <a href=#29>ADD</a>, you can have as many gates as needed.
<p>
Use <a href=#40>CONNECT</a> to specify which of the packages pads are
connected to the pins of each gate.
<p>
Save the library and you can <a href=#102>USE</a> it from the schematic or board
editor.
<a name=12>
<h1>Control Panel</h1>
The Control Panel is the top level window of EAGLE.
It contains a tree view on the left side, and an information window on the right side.
<h2>Directories</h2>
The top level items of the tree view represent the various types of EAGLE files.
Each of these can point to one or more directories that contain files of that type.
The location of these directories can be defined with the <a href=#14>directories dialog</a>.
If a top level item points to a single directory, the contents of that directory will
appear if the item is opened (either by clicking on the little symbol to the left, or by
double clicking the item). If such an item points to more directories, all of these
directories will be listed when the item is opened.
<h2>Context menu</h2>
The <a href=#13>context menu</a> of the tree items can be accessed by clicking on them with the right
mouse button. It contains options specific to the selected item.
<h2>Descriptions</h2>
The <i>Description</i> column of the tree view contains a short description of the
item (if available). These descriptions are derived from the first non-blank line
of the text from the following sources:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Directories</td> <td width=20><td>a file named DESCRIPTION in that directory</td></tr>
<tr><td>Libraries</td> <td width=20><td>the description of the library</td></tr>
<tr><td>Devices</td> <td width=20><td>the description of the device</td></tr>
<tr><td>Packages</td> <td width=20><td>the description of the package</td></tr>
<tr><td>Design Rules</td> <td width=20><td>the description of the design rules file</td></tr>
<tr><td>User Language Programs</td> <td width=20><td>the text defined with the <tt>#usage</tt> directive</td></tr>
<tr><td>Scripts</td> <td width=20><td>the comment at the beginning of the script file</td></tr>
<tr><td>CAM Jobs</td> <td width=20><td>the description of the CAM job</td></tr>
</table>
<h2>Drag&amp;drop</h2>
You can use <i>Drag&amp;Drop</i> to copy or move files and directories within the
tree view. It is also possible to drag a device or package to a schematic, board or library
window, respectively, and drop it there to add it to the drawing. User Language Programs
and Scripts will be executed if dropped onto an editor window, and Design Rules will be
applied to a board if dropped onto a board editor window. If a board, schematic or
library file is dropped onto its respective editor window, it will be loaded into the
editor.
All of these functions can also be accessed through the <i>context menu</i>
of the particular tree item.
<h2>Information window</h2>
The right hand side of the Control Panel displays information about the current item
in the tree view. That information is derived from the places listed above under
<i>Descriptions</i>. Devices and packages also show a preview of their contents.
<h2>Pulldown menu</h2>
The Control panel's <i>pulldown menu</i> contains the following options:
<h2>File</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>New </td><td width=20><td>create a new file</td></tr>
<tr><td>Open </td><td width=20><td>open an existing file</td></tr>
<tr><td>Open recent projects</td><td width=20><td>open a recently used project</td></tr>
<tr><td>Save all </td><td width=20><td>save all modified editor files</td></tr>
<tr><td>Close project </td><td width=20><td>close the current project</td></tr>
<tr><td>Exit </td><td width=20><td>exit from the program</td></tr>
</table>
<h2>View</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Refresh</td><td width=20><td>refresh the contents of the tree view</td></tr>
<tr><td>Sort </td><td width=20><td>change the sorting of the tree view</td></tr>
</table>
<h2>Options</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Directories... </td><td width=20><td>opens the <a href=#14>directories dialog</a></td></tr>
<tr><td>Backup... </td><td width=20><td>opens the <a href=#15>backup dialog</a></td></tr>
<tr><td>User interface... </td><td width=20><td>opens the <a href=#16>user interface dialog</a></td></tr>
<tr><td>Window positions...</td><td width=20><td>opens the <a href=#17>window positions dialog</a></td></tr>
</table>
<h2>Window</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Control Panel </td><td width=20><td>switch to the Control Panel</td></tr>
<tr><td>1 Schematic - ... </td><td width=20><td>switch to window number 1</td></tr>
<tr><td>2 Board - ... </td><td width=20><td>switch to window number 2</td></tr>
</table>
<h2>Help</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>General </td><td width=20><td>opens a general help page</td></tr>
<tr><td>Context </td><td width=20><td>opens the help page for the current context</td></tr>
<tr><td>Control Panel </td><td width=20><td>opens the help page you are currently looking at</td></tr>
<tr><td>EAGLE License </td><td width=20><td>opens the <a href=#346>license dialog</a></td></tr>
<tr><td>Check for Update </td><td width=20><td><a href=#18>checks</a> if a new version of EAGLE is available</td></tr>
<tr><td>About EAGLE </td><td width=20><td>displays details on your EAGLE version and <a href=#345>license</a></td></tr>
</table>
<h2>Status line</h2>
The status line at the bottom of the Control Panel contains
the full name of the currently selected item.
<a name=13>
<h1>Context Menus</h1>
Clicking on an item in the <a href=#12>Control Panel</a>
with the right mouse button opens a context menu which allows
the following actions (not all of them may be present on a particular item):
<h2>New Folder</h2>
Creates a new folder below the selected folder and puts the newly created tree
item into <i>Rename</i> mode.
<h2>Edit Description</h2>
Loads the DESCRIPTION file of a directory into the HTML editor.
<h2>Rename</h2>
Puts the tree item's text into edit mode, so that it can be renamed.
<h2>Copy</h2>
Opens a file dialog in which you can enter a name to which to copy this file or directory.
You can also use <i>Drag&amp;Drop</i> to do this.
<h2>Delete</h2>
Deletes the file or directory (you will be prompted to confirm that you really want this to happen).
<h2>Use</h2>
Marks this library to be <i>used</i> when searching for devices or packages.
You can also click on the icon in the second column of the tree view to toggle this flag.
<h2>Use all</h2>
Marks all libraries in the Libraries path to be <i>used</i> when searching for devices or packages.
<h2>Use none</h2>
Removes the <i>use</i> marks from all libraries (including such libraries that are not
in the Libraries path).
<h2>Update</h2>
Updates all parts used from this library in the loaded board and schematic.
<h2>Update in Library</h2>
Updates all packages used from this library in the loaded library.
<h2>Add to Schematic</h2>
Starts the <a href=#29>ADD</a> command in the schematic window with this device.
You can also use <i>Drag&amp;Drop</i> to do this.
<h2>Add to Board</h2>
Starts the <a href=#29>ADD</a> command in the board window with this package.
You can also use <i>Drag&amp;Drop</i> to do this.
<h2>Copy to Library</h2>
Copies the selected device set or package into the loaded library.
You can also use <i>Drag&amp;Drop</i> to do this.
<h2>New variant in Library</h2>
Creates a new package variant with the selected package in the current
device set of the loaded library.
You can also use <i>Drag&amp;Drop</i> to do this.
<h2>Open/Close Project</h2>
Opens or closes this project.
You can also click on the icon in the second column of the tree view to do this.
<h2>New</h2>
Opens a window with a new file of the given type.
<h2>Open</h2>
Opens this file in the propper window.
You can also use <i>Drag&amp;Drop</i> to do this.
<h2>Print...</h2>
Prints the file to the system printer. See the chapter on
<a href=#109>printing to the system printer</a> for more
information on how to use the print dialogs.
<p>
Printing a file through this context menu option will always print the file
as it is on disk, even if you have an open editor window in which you have
modified the file! Use the <a href=#79>PRINT</a> command to
print the drawing from an open editor window.<br>
<b>Please note that polygons in boards will not be automatically calculated
when printing via the context menu! Only the outlines will be drawn.
To print polygons in their calculated shape you have to load the drawing
into an editor window, enter <a href=#81>RATSNEST</a>
and then <a href=#79>PRINT</a></b>.
<h2>Run in ...</h2>
Runs this User Language Program in the current schematic, board or library.
You can also use <i>Drag&amp;Drop</i> to do this.
<h2>Execute in ...</h2>
Executes this script file in the current schematic, board or library.
You can also use <i>Drag&amp;Drop</i> to do this.
<h2>Load into Board</h2>
Loads this set of Design Rules into the current board.
You can also use <i>Drag&amp;Drop</i> to do this.
<a name=14>
<h1>Directories</h1>
The <i>Directories</i> dialog is used to define the directory paths
in which to search for files.
<p>
All entries may contain one or more directories, separated by a colon (<b><tt>':'</tt></b>),
in which to look for the various types of files.
<table><tr><td valign="top"><img src="platforms-win.png"></td><td valign="middle">
On <b>Windows</b> the individual directory names are separated by a semicolon (<b><tt>';'</tt></b>).
</td></tr></table>
When entering an <a href=#70>OPEN</a>,
<a href=#102>USE</a>, <a href=#91>SCRIPT</a> or
<a href=#90>RUN</a> command, these paths will be searched
left-to-right to locate the file.
If the file dialog is used to access a file of one of these types, the directory into
which the user has navigated through the file dialog will be implicitly added to the
end of the respective search path.
<p>
The special variables <tt>$HOME</tt> and <tt>$EAGLEDIR</tt> can be used to reference
the user's home directory and the EAGLE program directory, respectively.
<table><tr><td valign="top"><img src="platforms-win.png"></td><td valign="middle">
On <b>Windows</b> the value of <tt>$HOME</tt> is either that of the environment variable
HOME (if set), or the value of the registry key "HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\Shell&nbsp;Folders\Personal",
which contains the actual name of the "My Documents" directory.
</td></tr></table>
<a name=15>
<h1>Backup</h1>
The <i>Backup</i> dialog allows you to customize the
<a href=#340>automatic backup</a> function.
<h2>Maximum backup level</h2>
Defines how many backup copies of your EAGLE data files shall be kept
when regularly saving a file to disk with the WRITE command
(default is 9).
<h2>Auto backup interval (minutes)</h2>
Defines the maximum time after which EAGLE automatically creates a safety backup
copy of any modified drawing (default is 5).
<h2>Automatically save project file</h2>
If this option is checked, your project settings will be automatically saved when
you exit from the program.
Note that if you uncheck this option while you have a project open, this
project will not be saved when you close it, and thus this setting will not
be stored in the project's eagle.epf file. This means that the next time you
open the project, this option will be checked again. If you want this option
to remain unchecked for the current project, you need to manually select
"File/Save all" from the pulldown menu after unchecking this option.
<a name=16>
<h1>User Interface</h1>
The <i>User interface</i> dialog allows you to customize the
appearance of the layout, schematic and library
<a href=#21>editor windows</a>.
<h2>Controls</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Pulldown menu </td><td width=20><td>activates the pulldown menu at the top of the editor window</td></tr>
<tr><td>Action toolbar </td><td width=20><td>activates the action toolbar containing buttons for "File", "Print" etc.</td></tr>
<tr><td>Parameter toolbar </td><td width=20><td>activates the dynamic parameter toolbar, which contains all the parameters that are available for the currently active command</td></tr>
<tr><td>Command buttons </td><td width=20><td>activates the command buttons</td></tr>
<tr><td>Command texts </td><td width=20><td>activates the textual command menu</td></tr>
<tr><td>Sheet thumbnails </td><td width=20><td>aktivates the sheet thumbnail preview</td></tr>
</table>
<h2>Layout</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Background </td><td width=20><td>selects a black, white or colored background for the layout mode</td></tr>
<tr><td>Cursor </td><td width=20><td>selects a small or large cursor for the layout mode</td></tr>
</table>
<h2>Schematic</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Background </td><td width=20><td>selects a black, white or colored background for the schematic mode</td></tr>
<tr><td>Cursor </td><td width=20><td>selects a small or large cursor for the schematic mode</td></tr>
</table>
<h2>Help</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Bubble help </td><td width=20><td>activates the "Bubble Help" function, which pops up a short hint about the meaning of several buttons when moving the cursor over them</td></tr>
<tr><td>User guidance </td><td width=20><td>activates the "User Guidance" function, which displays a helping text telling the user what would be the next meaningful action when a command is active</td></tr>
</table>
<h2>Misc</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Always vector font </td><td width=20><td>always displays texts in drawings with the builtin vector font, regardless of which font is actually set for a particular text</td></tr>
<tr><td>Mouse wheel zoom </td><td width=20><td>defines the zoom factor that will be used to zoom in and out of an editor window when the mouse wheel is turned ('0' disables this feature, the sign of this value defines the direction of the zoom operation)</td></tr>
</table>
<a name=17>
<h1>Window positions</h1>
The <i>Window positions</i> dialog allows you to store the positions
of all currently open windows, so that later, when a window of the same
type is opened again, it will appear at the same position as before.
<p>
You can also delete all stored window positions, so that the window manager
can decide again where to place newly opened windows.
<a name=18>
<h1>Check for Update</h1>
The option "Help/Check for Update" in the Control Panel's pulldown menu opens
a dialog that displays whether there is a new version of EAGLE available on
the CadSoft server.
<p>
The <b>Configure</b> button opens a dialog in which you can specify if and
how often a check for new versions should be done automatically upon program
start (by default it checks once per day). If you need to use a proxy to access
the Internet, this can also be specified in the configuration dialog. Enter
the name in the form
<pre>
hostname:port
</pre>
where <i>hostname</i> is the full name of the proxy host, without any
<tt>http://</tt> prefix, and <i>port</i> is an optional port number.
<p>
If you would like to be informed about beta versions of EAGLE, you can check
the "Also check for beta versions" box.
<a name=19>
<h1>Keyboard and Mouse</h1>
The <i>modifier keys</i> (<tt>Alt</tt>, <tt>Ctrl</tt> and <tt>Shift</tt>) are used
to modify the behaviour of certain mouse actions.
Note that depending on which operating system or window manager you use, some of these
keys (in combination with mouse events) may not be delivered to applications, which means
that some of the functions described here may not be available.
<h2>Alt</h2>
Pressing the <tt>Alt</tt> key switches to an alternate <a href=#53>GRID</a>.
This can typically be a finer grid than the normal one, which allows you to quickly
do some fine positioning in a dense area, for instance, where the normal grid might
be too coarse.
The alternate grid remains active as long as the <tt>Alt</tt> key is held pressed down.
<h2>Ctrl</h2>
Pressing the <tt>Ctrl</tt> key while clicking on the right mouse button toggles
between corresponding wire bend styles (only applies to commands that support wire
bend styles, like, for instance, <a href=#106>WIRE</a>).
<p>
The <tt>Ctrl</tt> key together with the left mouse button controls special functionality
of individual commands, like, for instance, selecting an object at its origin with the
<a href=#67>MOVE</a> command.
<p>
If a command can select a group, the <tt>Ctrl</tt> key must be pressed together with
the right mouse button when selecting the group (otherwise a context menu for the
selected object would be opened).
<p>
<table><tr><td valign="top"><img src="platforms-mac.png"></td><td valign="middle">
On <b>Mac OS X</b> the <tt>Cmd</tt> key has to be used instead of the <tt>Ctrl</tt> key.
</td></tr></table>
<h2>Shift</h2>
Pressing the <tt>Shift</tt> key while clicking on the right mouse button reverses
the direction in which the wire bend styles are switched through (only applies to
commands that support wire bend styles, like, for instance, <a href=#106>WIRE</a>).
<p>
The <tt>Shift</tt> key together with the left mouse button controls special functionality
of individual commands, like, for instance, deleting a higher level object with the
<a href=#43>DELETE</a> command.
<h2>Esc</h2>
Pressing the <tt>Esc</tt> key when a command is active will cancel the current
activity of that command without canceling the entire command (if there is text
in the command line, that text will be deleted first, and the next press of the
<tt>Esc</tt> key will act on the command).
For the <a href=#67>MOVE</a> command, for example, this means
that an object that is currently attached to the cursor
will be dropped and an other object can be selected.
<h2>Crsr-Up/Down</h2>
The keys <tt>Crsr-Up</tt> (cursor up) and <tt>Crsr-Down</tt> (cursor down) can be used in the
command line of an editor window to scroll through the command history.
<h2>Function Keys</h2>
Function keys can be assigned any commands by using the <a href=#31>ASSIGN</a> command.
<h2>Left Mouse Button</h2>
The left mouse button is generally used to select, draw or place objects.
<h2>Center Mouse Button</h2>
The center mouse button changes the current layer or mirrors the object currently
attached to the mouse cursor.
<p>
The following commands support the center mouse button:
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><a href=#29>ADD</a> </td><td width=20><td>mirror part</td></tr>
<tr><td><a href=#30>ARC</a> </td><td width=20><td>change active layer</td></tr>
<tr><td><a href=#37>CIRCLE</a> </td><td width=20><td>change active layer</td></tr>
<tr><td><a href=#41>COPY</a> </td><td width=20><td>mirror object</td></tr>
<tr><td><a href=#58>INVOKE</a> </td><td width=20><td>mirror gate</td></tr>
<tr><td><a href=#60>LABEL</a> </td><td width=20><td>change active layer</td></tr>
<tr><td><a href=#67>MOVE</a> </td><td width=20><td>mirror object or group</td></tr>
<tr><td><a href=#74>PASTE</a> </td><td width=20><td>mirror group</td></tr>
<tr><td><a href=#77>POLYGON</a> </td><td width=20><td>change active layer</td></tr>
<tr><td><a href=#82>RECT</a> </td><td width=20><td>change active layer</td></tr>
<tr><td><a href=#89>ROUTE</a> </td><td width=20><td>change active layer</td></tr>
<tr><td><a href=#96>SMD</a> </td><td width=20><td>change active layer</td></tr>
<tr><td><a href=#99>TEXT</a> </td><td width=20><td>change active layer</td></tr>
<tr><td><a href=#106>WIRE</a> </td><td width=20><td>change active layer</td></tr>
</table>
<p>
Click&amp;Drag with the center mouse button will pan the drawing within the editor
window.
<h2>Right Mouse Button</h2>
The right mouse button is mostly used to select a group, rotate objects attached to
the mouse cursor, change wire bend styles and several other command specific functions.
<p>
When selecting an object with the right mouse button, a context specific popup menu is
displayed from which commands that apply to this object can be selected.
If there is currently a command active that can be applied to a group, the popup menu
will contain an entry for this.
<p>
The following commands support the right mouse button:
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><a href=#29>ADD</a> </td><td width=20><td>rotate part</td></tr>
<tr><td><a href=#30>ARC</a> </td><td width=20><td>change direction of arc</td></tr>
<tr><td><a href=#35>BUS</a> </td><td width=20><td>change wire bend</td></tr>
<tr><td><a href=#36>CHANGE</a> </td><td width=20><td>apply change to group</td></tr>
<tr><td><a href=#43>DELETE</a> </td><td width=20><td>delete group</td></tr>
<tr><td><a href=#54>GROUP</a> </td><td width=20><td>close polygon</td></tr>
<tr><td><a href=#58>INVOKE</a> </td><td width=20><td>rotate gate</td></tr>
<tr><td><a href=#60>LABEL</a> </td><td width=20><td>rotate label</td></tr>
<tr><td><a href=#65>MIRROR</a> </td><td width=20><td>mirror group</td></tr>
<tr><td><a href=#67>MOVE</a> </td><td width=20><td>rotate object, select group</td></tr>
<tr><td><a href=#69>NET</a> </td><td width=20><td>change wire bend</td></tr>
<tr><td><a href=#73>PAD</a> </td><td width=20><td>rotate pad</td></tr>
<tr><td><a href=#74>PASTE</a> </td><td width=20><td>rotate group</td></tr>
<tr><td><a href=#75>PIN</a> </td><td width=20><td>rotate pin</td></tr>
<tr><td><a href=#77>POLYGON</a> </td><td width=20><td>change wire bend</td></tr>
<tr><td><a href=#87>RIPUP</a> </td><td width=20><td>ripup group</td></tr>
<tr><td><a href=#88>ROTATE</a> </td><td width=20><td>rotate group</td></tr>
<tr><td><a href=#89>ROUTE</a> </td><td width=20><td>change wire bend</td></tr>
<tr><td><a href=#96>SMD</a> </td><td width=20><td>rotate smd</td></tr>
<tr><td><a href=#97>SPLIT</a> </td><td width=20><td>change wire bend</td></tr>
<tr><td><a href=#99>TEXT</a> </td><td width=20><td>rotate text</td></tr>
<tr><td><a href=#106>WIRE</a> </td><td width=20><td>change wire bend</td></tr>
</table>
<h2>Mouse Wheel</h2>
Inside an editor window the mouse wheel can be used to zoom in and out.
<a name=20>
<h1>Selecting objects in dense areas</h1>
When you try to select an object at a position where several objects
are placed close together, a four way arrow and the question
<p>
<i>Select highlighted object? (left=yes, right=next, ESC=cancel)</i>
<p>
indicates that you can now choose one of these objects.
<p>
Press the right mouse button to switch to the next object.
<p>
Press the left mouse button to select the highlighted object.
<p>
Press Esc to cancel the selection procedure.
<p>
The command
<pre>
<a href=#92>SET</a> Select_Factor select_radius;
</pre>
defines the selection radius.
<p>
If the original selection was done with the right mouse button, a context specific
popup menu will be displayed which applies to the first selected object, and which
contains "Next" as the first entry. Clicking on this entry will cyclically switch
through the objects within the selection radius.
<a name=21>
<h1>Editor Windows</h1>
EAGLE knows different types of data files, each of which has its own
type of editor window. By double clicking on one of the items in the
<a href=#12>Control Panel</a> or by selecting a file from the
<b>File/Open</b> menu, an editor
window suitable for that file will be opened.
<ul>
<li><a href=#22>Library Editor</a>
<li><a href=#25>Schematic Editor</a>
<li><a href=#24>Board Editor</a>
<li><a href=#26>Text Editor</a>
</ul>
<a name=22>
<h1>Library Editor</h1>
The <i>Library Editor</i> is used to edit a part library (<tt>*.lbr</tt>).
<p>
After opening a new library editor window, the edit area will be empty and
you will have to use the <a href=#47>EDIT</a> command to select
which package, symbol or device you want to edit or create.
<a name=23>
<h1>Edit Library Object</h1>
In library edit mode you can edit packages, symbols, and devices.
<p>
<b>Package:</b> the package definition.
<p>
<b>Symbol:</b> the symbol as it appears in the circuit diagram.
<p>
<b>Device:</b> definition of the whole component. Contains one or more
package variants and one or several symbols (e.g. gates).
The symbols can be different from each other.
<p>
Click on the <b>Dev</b>, <b>Pac</b> or
<b>Sym</b> button to select Device, Packages or Symbols,
respectively.
<p>
If you want to create a new object, write the name of the new object into
the <b>New</b> field. You can also edit an existing object
by typing its name into this field. If you omit the extension, an object
of the type indicated by the <b>Choose...</b> prompt will be
loaded. Otherwise an object of the type indicated by the extension will
be loaded.
<p>
If your <a href=#345>license</a> does not include
the Schematic Module, the object type buttons (<b>Dev</b>...)
will not appear in the menu.
<a name=24>
<h1>Board Editor</h1>
The <i>Board Editor</i> is used to edit a board (<tt>*.brd</tt>).
<p>
When there is a schematic file (<tt>*.sch</tt>) with the same name as the
board file (in the same directory), opening a board editor window will
automatically open a <a href=#25>Schematic Editor</a>
window containing that file and will put it on the desktop
as an icon. This is necessary to have the schematic file loaded when editing
the board causes modifications that have to be
<a href=#341>back-annotated</a>
to the schematic.
<a name=25>
<h1>Schematic Editor</h1>
The <i>Schematic Editor</i> is used to edit a schematic (<tt>*.sch</tt>).
<p>
When there is a board file (<tt>*.brd</tt>) with the same name as the
schematic file (in the same directory), opening a schematic editor window will
automatically open a <a href=#24>Board Editor</a>
window containing that file and will put it on the desktop
as an icon. This is necessary to have the board file loaded when editing
the schematic causes modifications that have to be
<a href=#341>forward-annotated</a>
to the board.
<p>
The combo box in the action toolbar of the schematic editor window allows
you to switch between the various sheets of the schematic, or to add new
sheets to the schematic (this can also be done using the
<a href=#47>EDIT</a> command).
<a name=26>
<h1>Text Editor</h1>
The <i>Text Editor</i> is used to edit any kind of text.
<p>
The text must be a pure ASCII file and must not contain any control codes.
The main area of use for the text editor is writing
<a href=#138>User Language Programs</a> and
<a href=#91>Script files</a>.
<h2>Using an external text editor</h2>
If you prefer to use an external text editor instead of EAGLE's builtin text
editor, you can specify the command necessary to start that editor in the
"Options/User interface" dialog.
<p>
Within that command the following placeholders will be replaced with
actual values:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>%C</tt></td><td width=20><td>the column in which to place the cursor (currently always <tt>1</tt>)</td></tr>
<tr><td><tt>%F</tt></td><td width=20><td>the name of the file to load</td></tr>
<tr><td><tt>%L</tt></td><td width=20><td>the line in which to place the cursor</td></tr>
</table>
<p>
If the command consists only of a hyphen (<tt>'-'</tt>), EAGLE will never open
a text editor window. This may be useful for people who always start their text
editor by themselves.
<p>
The following restrictions apply when using an external text editor:
<ul>
<li>The external text editor runs as a separate process, and EAGLE has no way of
knowing whether the loaded file has been modified or not. It is up to you to
save the file after you have made modifications.
<li>If the same file is loaded into the text editor several times, it depends on
the configuration of the text editor in use whether it opens a new window each
time, or whether it loads the file into the same window.
<li>The external text editor windows do not show up in EAGLE's window list, and
are therefore not stored in the project file, and are not reopened when the project
is opened again later.
<li>When leaving EAGLE, the external text editor processes will be terminated.
It depends on the operating system and the particular text editor whether or
not you are queried if a file has been modified and should be saved.
<li>The "File/Save all" function will not save files edited with an external text editor.
<li>The update report that may be given when loading a file from an older version
of EAGLE is always displayed with the internal text editor.
</ul>
<a name=27>
<h1>Editor Commands</h1>
<h2>Change Mode/File Commands</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><a href=#39>CLOSE</a> </td><td width=20><td>Close drawing after editing</td></tr>
<tr><td><a href=#47>EDIT</a> </td><td width=20><td>Load/create a drawing</td></tr>
<tr><td><a href=#50>EXPORT</a> </td><td width=20><td>Generate ASCII list (e.g. netlist)</td></tr>
<tr><td><a href=#70>OPEN</a> </td><td width=20><td>Open library for editing</td></tr>
<tr><td><a href=#80>QUIT</a> </td><td width=20><td>Quit EAGLE</td></tr>
<tr><td><a href=#84>REMOVE</a> </td><td width=20><td>Delete files/library elements</td></tr>
<tr><td><a href=#91>SCRIPT</a> </td><td width=20><td>Execute command file</td></tr>
<tr><td><a href=#102>USE</a> </td><td width=20><td>Load library for placing elements</td></tr>
<tr><td><a href=#107>WRITE</a> </td><td width=20><td>Save drawing/library</td></tr>
</table>
<h2>Edit Drawings or Libraries</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><a href=#29>ADD</a> </td><td width=20><td>Add element to drawing/symbol to device</td></tr>
<tr><td><a href=#30>ARC</a> </td><td width=20><td>Draw arc</td></tr>
<tr><td><a href=#32>ATTRIBUTE</a> </td><td width=20><td>Define attributes</td></tr>
<tr><td><a href=#37>CIRCLE</a> </td><td width=20><td>Draw circle</td></tr>
<tr><td><a href=#38>CLASS</a> </td><td width=20><td>Define net classes</td></tr>
<tr><td><a href=#41>COPY</a> </td><td width=20><td>Copy objects/elements</td></tr>
<tr><td><a href=#42>CUT</a> </td><td width=20><td>Cut previously defined group</td></tr>
<tr><td><a href=#43>DELETE</a> </td><td width=20><td>Delete objects</td></tr>
<tr><td><a href=#44>DESCRIPTION</a> </td><td width=20><td>Change an object's description</td></tr>
<tr><td><a href=#54>GROUP</a> </td><td width=20><td>Define group for upcoming operation</td></tr>
<tr><td><a href=#56>HOLE</a> </td><td width=20><td>Define non-conducting hole</td></tr>
<tr><td><a href=#61>LAYER</a> </td><td width=20><td>Create/change layer</td></tr>
<tr><td><a href=#65>MIRROR</a> </td><td width=20><td>Mirror objects</td></tr>
<tr><td><a href=#66>MITER</a> </td><td width=20><td>Miter wire joints</td></tr>
<tr><td><a href=#67>MOVE</a> </td><td width=20><td>Move or rotate objects</td></tr>
<tr><td><a href=#68>NAME</a> </td><td width=20><td>Name object</td></tr>
<tr><td><a href=#74>PASTE</a> </td><td width=20><td>Paste previously cut group to a drawing</td></tr>
<tr><td><a href=#77>POLYGON</a> </td><td width=20><td>Draw polygon</td></tr>
<tr><td><a href=#82>RECT</a> </td><td width=20><td>Draw rectangle</td></tr>
<tr><td><a href=#88>ROTATE</a> </td><td width=20><td>Rotate objects</td></tr>
<tr><td><a href=#95>SMASH</a> </td><td width=20><td>Prepare NAME/VALUE text for moving</td></tr>
<tr><td><a href=#97>SPLIT</a> </td><td width=20><td>Bend wires/lines (tracks, nets, etc.)</td></tr>
<tr><td><a href=#99>TEXT</a> </td><td width=20><td>Add text to a drawing</td></tr>
<tr><td><a href=#103>VALUE</a> </td><td width=20><td>Enter/change value for component</td></tr>
<tr><td><a href=#106>WIRE</a> </td><td width=20><td>Draw line or routed track</td></tr>
</table>
<h2>Special Commands for Boards</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><a href=#46>DRC</a> </td><td width=20><td>Perform design rule check</td></tr>
<tr><td><a href=#49>ERRORS</a> </td><td width=20><td>Show DRC errors</td></tr>
<tr><td><a href=#62>LOCK</a> </td><td width=20><td>Lock component's position</td></tr>
<tr><td><a href=#81>RATSNEST</a> </td><td width=20><td>Show shortest air lines</td></tr>
<tr><td><a href=#86>REPLACE</a> </td><td width=20><td>Replace component</td></tr>
<tr><td><a href=#87>RIPUP</a> </td><td width=20><td>Ripup routed track</td></tr>
<tr><td><a href=#89>ROUTE</a> </td><td width=20><td>Route signal</td></tr>
<tr><td><a href=#94>SIGNAL</a> </td><td width=20><td>Define signal (air line)</td></tr>
<tr><td><a href=#104>VIA</a> </td><td width=20><td>Place via-hole</td></tr>
</table>
<h2>Special Commands for Schematics</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><a href=#34>BOARD</a> </td><td width=20><td>Create a board from a schematic</td></tr>
<tr><td><a href=#35>BUS</a> </td><td width=20><td>Draw bus line</td></tr>
<tr><td><a href=#48>ERC</a> </td><td width=20><td>Perform electrical rule check</td></tr>
<tr><td><a href=#52>GATESWAP</a> </td><td width=20><td>Swap equivalent 'gates'</td></tr>
<tr><td><a href=#58>INVOKE</a> </td><td width=20><td>Add certain 'gate' from a placed device</td></tr>
<tr><td><a href=#59>JUNCTION</a> </td><td width=20><td>Place connection point</td></tr>
<tr><td><a href=#60>LABEL</a> </td><td width=20><td>Provide label to bus or net</td></tr>
<tr><td><a href=#69>NET</a> </td><td width=20><td>Define net</td></tr>
<tr><td><a href=#76>PINSWAP</a> </td><td width=20><td>Swap equivalent pins</td></tr>
</table>
<h2>Special Commands for Libraries</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><a href=#40>CONNECT</a> </td><td width=20><td>Define pin/pad assignment</td></tr>
<tr><td><a href=#72>PACKAGE</a> </td><td width=20><td>Define package for device</td></tr>
<tr><td><a href=#73>PAD</a> </td><td width=20><td>Add pad to a package</td></tr>
<tr><td><a href=#75>PIN</a> </td><td width=20><td>Add pin to a symbol</td></tr>
<tr><td><a href=#78>PREFIX</a> </td><td width=20><td>Define default prefix for device</td></tr>
<tr><td><a href=#84>REMOVE</a> </td><td width=20><td>Delete library elements</td></tr>
<tr><td><a href=#85>RENAME</a> </td><td width=20><td>Rename symbol/package/device</td></tr>
<tr><td><a href=#96>SMD</a> </td><td width=20><td>Add smd pad to a package</td></tr>
<tr><td><a href=#98>TECHNOLOGY</a> </td><td width=20><td>Define technologies for a device</td></tr>
<tr><td><a href=#103>VALUE</a> </td><td width=20><td>Define if value text can be changed</td></tr>
</table>
<h2>Change Screen Display and User Interface</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><a href=#31>ASSIGN</a> </td><td width=20><td>Assign keys</td></tr>
<tr><td><a href=#36>CHANGE</a> </td><td width=20><td>Change parameters</td></tr>
<tr><td><a href=#45>DISPLAY</a> </td><td width=20><td>Display/hide layers</td></tr>
<tr><td><a href=#53>GRID</a> </td><td width=20><td>Define grid/unit</td></tr>
<tr><td><a href=#64>MENU</a> </td><td width=20><td>Configure command menu</td></tr>
<tr><td><a href=#92>SET</a> </td><td width=20><td>Set program parameters</td></tr>
<tr><td><a href=#105>WINDOW</a> </td><td width=20><td>Choose screen window</td></tr>
</table>
<h2>Miscellaneous Commands</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><a href=#33>AUTO</a> </td><td width=20><td>Start Autorouter</td></tr>
<tr><td><a href=#55>HELP</a> </td><td width=20><td>Show help page</td></tr>
<tr><td><a href=#57>INFO</a> </td><td width=20><td>Show information about object</td></tr>
<tr><td><a href=#63>MARK</a> </td><td width=20><td>Set/remove mark (for measuring)</td></tr>
<tr><td><a href=#71>OPTIMIZE</a> </td><td width=20><td>Optimize (join) wire segments</td></tr>
<tr><td><a href=#79>PRINT</a> </td><td width=20><td>Print to the system printer</td></tr>
<tr><td><a href=#83>REDO</a> </td><td width=20><td>Redo commands</td></tr>
<tr><td><a href=#90>RUN</a> </td><td width=20><td>Run User Language Program</td></tr>
<tr><td><a href=#93>SHOW</a> </td><td width=20><td>Highlight object</td></tr>
<tr><td><a href=#100>UNDO</a> </td><td width=20><td>Undo commands</td></tr>
<tr><td><a href=#101>UPDATE</a> </td><td width=20><td>Update library objects</td></tr>
</table>
<a name=28>
<h1>Command Syntax</h1>
EAGLE commands can be entered in different ways:
<ul>
<li>with the keyboard as text
<li>with the mouse by selecting menu items or clicking on icons
<li>with assigned keys (see <a href=#31>ASSIGN</a> command)
<li>with command files (see <a href=#91>SCRIPT</a> command)
</ul>
All these methods can be mixed.
<p>
Commands and parameters in <tt>CAPITAL LETTERS</tt> are entered directly (or
selected in the command menu with the mouse). For the input there is
no difference between small and capital letters.
<p>
Parameters in <tt>lowercase letters</tt> are replaced by names, number values or
key words. Example:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Syntax: </td><td width=20><td><tt>GRID grid_size grid_multiple;</tt></td></tr>
<tr><td>Input: </td><td width=20><td><tt>GRID 1 10;</tt></td></tr>
</table>
<h2>Shorten key words</h2>
For command names and other key words, only so many characters must be
entered that they clearly differ from other key words.
<h2>Alternative Parameters</h2>
The sign | means that alternative parameters can be indicated. Example:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Syntax: </td><td width=20><td><tt>SET BEEP OFF | ON;</tt></td></tr>
<tr><td>Input: </td><td width=20><td><tt>SET BEEP OFF;</tt></td></tr>
<tr><td> </td><td width=20><td>or</td></tr>
<tr><td> </td><td width=20><td><tt>SET BEEP ON;</tt></td></tr>
</table>
<h2>Repetition Points</h2>
The signs .. mean that the function can be executed several times
or that several parameters of the same type are allowed. Example:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Syntax: </td><td width=20><td><tt>DISPLAY option layer_name..</tt></td></tr>
<tr><td>Input: </td><td width=20><td><tt>DISPLAY TOP PINS VIAS</tt></td></tr>
</table>
<h2>Coordinates</h2>
The sign &#149; normally means that an object has to be selected with the
left mouse button at this point in the command. Example:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Syntax: </td><td width=20><td><tt>MOVE &#149; &#149;..</tt></td></tr>
<tr><td>Input: </td><td width=20><td><tt>MOVE</tt></td></tr>
<tr><td> </td><td width=20><td><tt>Mouse click on the first element to be moved</tt></td></tr>
<tr><td> </td><td width=20><td><tt>Mouse click on the target position</tt></td></tr>
<tr><td> </td><td width=20><td><tt>Mouse click on the second element to be moved</tt></td></tr>
<tr><td> </td><td width=20><td><tt>etc.</tt></td></tr>
</table>
<p>
This example also explains the meaning of the repetition points for
commands with mouse clicks.
<p>
For the program each mouse click is the input of a coordinate. If
coordinates are to be entered as text, the input via the keyboard
must be as follows:
<pre>
(x y)
</pre>
x and y are numbers in the unit which has been selected with the GRID
command. The input as text is mainly required for script files.<br>
If a unit other than the one selected with the GRID command shall be used,
it can be appended to the given coordinates, as in
<pre>
(100mil 200mil)
</pre>
Allowed units are <tt>mm</tt>, <tt>mic</tt>, <tt>mil</tt> and <tt>in</tt>.
It is possible to use different units for x and y.<br>
The special coordinate
<pre>
(@)
</pre>
can be used to reference the current position of the mouse cursor within
the draw window. For example, the input
<pre>
MOVE R1 (@)
</pre>
would move the part named R1 to the place currently pointed to with the mouse.
<p>
Any combination of the following modifiers may follow the opening brace
in order to simulate a particular key that is held pressed with the
"mouse click" or to change the type of coordinates:
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>&gt;</tt></td><td width=20><td>right mouse button click</td></tr>
<tr><td><tt>A </tt></td><td width=20><td>Alt key</td></tr>
<tr><td><tt>C </tt></td><td width=20><td>Ctrl key</td></tr>
<tr><td><tt>P </tt></td><td width=20><td>Polar coordinates (relative to the <a href=#63>mark</a>, x = radius, y = angle in degrees, counterclockwise)</td></tr>
<tr><td><tt>R </tt></td><td width=20><td>Relative coordinates (relative to the <a href=#63>mark</a>)</td></tr>
<tr><td><tt>S </tt></td><td width=20><td>Shift key</td></tr>
</table>
For example, the input
<pre>
(CR&gt; 1 2)
</pre>
would result in a "right button mouse click" at (1&nbsp;2) relative to the <a href=#63>mark</a>,
with the Ctrl key held down (of course what happens with this kind of input
will depend on the actual command). Note that if there is currently no mark
defined, coordinates with <tt>R</tt> or <tt>P</tt> will be relative to the
drawing's origin. Also, the modifier characters are not case sensitive, their
sequence doesn't matter and there doesn't have to be a blank between them and
the first coordinate digit. So the above example could also be written as
<tt>(r&gt;c1&nbsp;2)</tt>.
Values entered as "polar coordinates" will be stored internally as the corresponding
pair of (x&nbsp;y) coordinates.
<p>
As an example for entering coordinates as text let's assume you wish to enter the exact
dimensions for board outlines:
<pre>
GRID 1 MM;
CHANGE LAYER DIMENSION;
WIRE 0 (0 0) (160 0) (160 100) (0 100) (0 0);
GRID LAST;
</pre>
<h2>Decimal numbers</h2>
When entering decimal numbers in the command line of the editor window or in
dialog input fields, you can use the comma as the decimal delimiter (as in <tt>12,34</tt>),
if your locale settings allow this. However, when writing a script or a ULP that
returns EAGLE commands through the <tt>exit()</tt> function, you should always
use the 'dot' as the decimal delimiter (as in <tt>12.34</tt>), because otherwise
your script or ULP might not work on other systems. In general, it is recommended
to always use the 'dot' as the decimal delimiter.
<h2>Semicolon</h2>
The semicolon (';') terminates commands. A command needs to be terminated
with a semicolon if there fewer than the maximum possible number of options.
For example the command
<pre>
WINDOW;
</pre>
redraws the drawing window, whereas
<pre>
WINDOW FIT
</pre>
scales the drawing to fit entirely into the drawing window. There is no semicolon necessary here because it is already clear that the command is complete.
<a name=29>
<h1>ADD</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Add elements into a drawing.<br>
Add symbols into a device.
<dt>
<b>Syntax</b>
<dd>
<tt>ADD package_name[@library_name] [name] [orientation] &#149;..</tt><br>
<tt>ADD device_name[@library_name] [name [gate]] [orientation] &#149;..</tt><br>
<tt>ADD symbol_name [name] [options] &#149;..</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Center</mb> mirrors the part.<br>
<mb>Right</mb> rotates the part.<br>
<mb>Shift+Right</mb> reverses the direction of rotating.
</dl>
<b>See also</b> <a href=#101>UPDATE</a>,
<a href=#102>USE</a>,
<a href=#58>INVOKE</a>
<p>
The ADD command fetches a circuit symbol (gate) or a package from the active library and places it into the drawing.
<p>
During device definition the ADD command fetches a symbol into the device.
<p>
Usually you click the ADD command and select the package or symbol from the menu which opens. If necessary, parameters can now be entered via the keyboard.
<p>
If <tt>device_name</tt> contains wildcard characters (<tt>'*'</tt> or <tt>'?'</tt>) and more
than one device matches the pattern, the ADD dialog will be opened and the specific device
can be selected from the list.
Note that the <i>Description</i> checkbox in the ADD dialog will be unchecked after
any ADD command with a <tt>device_name</tt> has been given in the command line, no matter
if it contains wildcards or not. This is because a <tt>device_name</tt> entered in the
command line is only searched for in the device names, not in the descriptions.
<p>
The package or symbol is placed with the left button and rotated with the right button. After it has been placed another copy is immediately hanging from the cursor.
<p>
If there is already a device or package with the same name (from the same library) in the drawing,
and the library has been modified after the original object was added, an automatic
<a href=#101>library update</a> will be started and you will be asked whether
objects in the drawing shall be replaced with their new versions.
<b>Note: You should always run a <a href=#46>Design Rule Check</a> (DRC) and an
<a href=#48>Electrical Rule Check</a> (ERC) after a library update has been performed!</b>
<h2>Fetching a Package or Symbol into a Drawing</h2>
<h3>Wildcards</h3>
The ADD command can be used with wildcards (<tt>'*'</tt> or <tt>'?'</tt>) to find
a specific device. The ADD dialog offers a tree view of the matching
devices, as well as a preview of the device and package variant.
<p>
To add directly from a specific library, the command syntax
<pre>
ADD devicename@libraryname
</pre>
can be used. <tt>devicename</tt> may contain wildcards and <tt>libraryname</tt> can
be either a plain library name (like "ttl" or "ttl.lbr") or a full
file name (like "/home/mydir/myproject/ttl.lbr" or "../lbr/ttl").
<h3>Names</h3>
The package_name, device_name or symbol_name parameter is the name under which the package, device or symbol is stored in the library.
It is usually selected from a menu. The name parameter is the name which the element is to receive in the drawing.
If the name could be interpreted as an orientation or option, it must be enclosed in single quotes.
If a name is not explicitly given it will receive an automatically generated name.
<p>
Example:
<pre>
ADD DIL14 IC1 &#149;
</pre>
fetches the DIL14 package to the board and gives it the name IC1.
<p>
If no name is given in the schematic, the gate will receive the prefix that was specified in the device definition with <a href=#78>PREFIX</a>, expanded with a sequential number (e.g. IC1).
<p>
Example:
<pre>
ADD 7400 &#149; &#149; &#149; &#149; &#149;
</pre>
This will place a sequence of five gates from 7400 type components. Assuming that the prefix is defined as "IC" and that the individual gates within a 7400 have the names A..D, the gates in the schematic will be named IC1A, IC1B, IC1C, IC1D, IC2A. (If elements with the same prefix have already been placed the counting will proceed from the next sequential number.) See also <a href=#58>INVOKE</a>.
<p>
While an object is attached to the cursor, you can change the name under which
it will be added to the drawing. This allows you to add several parts of the same
type, but with different, explicitly defined names:
<p>
Example:
<pre>
ADD CAP C1 &#149; C5 &#149; C7 &#149;
</pre>
<h3>Particular Gates</h3>
To fetch a particular gate of a newly added device the name of that gate can be given following the part name:
<p>
Example:
<pre>
ADD 7400 IC1 A &#149;
</pre>
This is mainly useful if a schematic is to be generated through a script. Note that if a particular
gate is added, no other gates with add level MUST or ALWAYS will be fetched automatically, and you will have to
use the <a href=#58>INVOKE</a> command to invoke at least the MUST gates (otherwise
the <a href=#48>Electrical Rule Check</a> will report them as missing).
<h3>Orientation</h3>
This parameter defines the orientation of the object in the drawing.
Objects are normally rotated using the right mouse button.
In <a href=#91>Script</a> files textual descriptions of this parameter are used:
<p>
<b><tt>[S][M]Rnnn</tt></b>
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><b><tt>S</tt></b> </td><td width=20><td>sets the <b>S</b>pin flag, which disable keeping texts readable from the bottom or right side of the drawing (only available in a board context)</td></tr>
<tr><td><b><tt>M</tt></b> </td><td width=20><td>sets the <b>M</b>irror flag, which mirrors the object about the y-axis</td></tr>
<tr><td><b><tt>Rnnn</tt></b></td><td width=20><td>sets the <b>R</b>otation to the given value, which may be in the range <tt>0.0</tt>...<tt>359.9</tt> (at a resolution of 0.1 degrees) in a board context, or one of <tt>0</tt>, <tt>90</tt>, <tt>180</tt> or <tt>270</tt> in a schematic context (angles may be given as negative values, which will be converted to the corresponding positive value)</td></tr>
</table>
<p>
The key letters <b><tt>S</tt></b>, <b><tt>M</tt></b> and <b><tt>R</tt></b> may be given
in upper- or lowercase, and there must be at least <b><tt>R</tt></b> followed by a number.
<p>
If the <b>M</b>irror flag is set in an element as well as in a text within the
element's package, they cancel each other out.
The same applies to the <b>S</b>pin flag.
<p>
Examples:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>R0 </td><td width=20><td>no rotation</td></tr>
<tr><td>R90 </td><td width=20><td>rotated 90&deg; counterclockwise</td></tr>
<tr><td>R-90 </td><td width=20><td>rotated 90&deg; clockwise (will be converted to 270&deg;)</td></tr>
<tr><td>MR0 </td><td width=20><td>mirrored about the y-axis</td></tr>
<tr><td>SR0 </td><td width=20><td>spin texts</td></tr>
<tr><td>SMR33.3</td><td width=20><td>rotated 33.3&deg; counterclockwise, mirrored and spin texts</td></tr>
</table>
<p>
Default: R0
<p>
<pre>
ADD DIL16 R90 (0 0);
</pre>
places a 16-pin DIL package, rotated 90 degrees counterclockwise, at coordinates (0 0).
<h3>Error messages</h3>
An error message appears if a gate is to be fetched from a device which is not fully defined (see <a href=#34>BOARD</a> command). This can be prevented with the "<a href=#92>SET</a> CHECK_CONNECTS OFF;" command. Take care: The BOARD command will perform this check in any case. Switching it off is only sensible if no pcb is to be made.
<h2>Fetch Symbol into Device</h2>
During device definition the ADD command fetches a previously defined symbol into the device. Two parameters (swaplevel and addlevel) are possible, and these can be entered in any sequence. Both can be preset and changed with the <a href=#36>CHANGE</a> command. The value entered with the ADD command is also retained as a default value.
<h3>Swaplevel</h3>
The swaplevel is a number in the range 0..255, to which the following rules apply:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>0: </td><td width=20><td>The symbol (gate) can not be swapped with any other in the schematic.</td></tr>
<tr><td>1..255 </td><td width=20><td>The symbol (gate) can be swapped with any other symbol of the same type in the schematic that has the same swaplevel (including swapping between different devices).</td></tr>
</table>
<p>
Default: 0
<h3>Addlevel</h3>
The following possibilities are available for this parameter:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>Next</tt> </td><td width=20><td>If a device has more than one gate, the symbols are fetched into the schematic with Addlevel Next.</td></tr>
<tr><td><tt>Must</tt> </td><td width=20><td>If any symbol from a device is fetched into the schematic, then a symbol defined with Addlevel Must must also appear. This happens automatically. It cannot be deleted until all the other symbols in the device have been deleted. If the only symbols remaining from a device are Must-symbols, the DELETE command will delete the entire device.</td></tr>
<tr><td><tt>Always</tt> </td><td width=20><td>Like Must, although a symbol with Addlevel Always can be deleted and brought back into the schematic with <a href=#58>INVOKE</a>.</td></tr>
<tr><td><tt>Can</tt> </td><td width=20><td>If a device contains Next-gates, then Can-gates are only fetched if explicitly called with INVOKE. A symbol with Addlevel Can is only then fetched into the schematic with ADD if the device only contains Can-gates and Request-gates.</td></tr>
<tr><td><tt>Request</tt></td><td width=20><td>This property is usefully applied to devices' power-symbols. Request-gates can only be explicitly fetched into the schematic (INVOKE) and are not internally counted. The effect of this is that in devices with only one gate and one voltage supply symbol, the gate name is not added to the component name. In the case of a 7400 with four gates (plus power supply) the individual gates in the schematic are called, for example, IC1A, IC1B, IC1C and IC1D. A 68000 with only one <i>Gate</i>, the processor symbol, might on the other hand be called IC1, since its separate voltage supply symbol is not counted as a gate. </td></tr>
</table>
<p>
Example:
<pre>
ADD PWR 0 REQUEST &#149;
</pre>
fetches the PWR symbol (e.g. a power pin symbol), and defines a Swaplevel of 0 (not swappable) and the Addlevel <i>Request</i> for it.
<a name=30>
<h1>ARC</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Draw an arc of variable diameter, width, and length.
<dt>
<b>Syntax</b>
<dd>
<tt>ARC ['signal_name'] [CW | CCW] [ROUND | FLAT] [width] &#149; &#149; &#149;</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Center</mb> selects the layer.<br>
<mb>Right</mb> changes the orientation.
</dl>
<b>See also</b> <a href=#36>CHANGE</a>,
<a href=#106>WIRE</a>,
<a href=#37>CIRCLE</a>
<p>
The ARC command, followed by three mouse clicks on a drawing, draws
an arc of defined width. The first point defines a point on a circle,
the second its diameter. Entering the second coordinate reduces the
circle to a semi-circle, while the right button alters the direction
from first to second point. Entry of a third coordinate truncates
the semi-circle to an arc extending to a point defined by the intersection
of the circumference and a line between the third point and the arc
center.
<p>
The parameters CW and CCW enable you to define the direction of the
arc (clockwise or counterclockwise). ROUND and FLAT define whether the arc
endings are round or flat, respectively.
<h2>Signal name</h2>
The <tt>signal_name</tt> parameter is intended mainly to be used in
script files that read in generated data. If a <tt>signal_name</tt>
is given, the arc will be added to that signal and no
automatic checks will be performed.<br>
<b>This feature should be used with great care because it could result
in short circuits if an arc is placed in a way that it would connect
different signals. Please run a
<a href=#46>Design Rule Check</a> after using the ARC command
with the <tt>signal_name</tt> parameter!</b>
<h2>Line Width</h2>
The parameter "width" defines the thickness of the drawn line.
It can be changed or predefined with the command:
<pre>
CHANGE WIDTH width;
</pre>
The adjusted width is identical to the line width for wires.
<p>
Arcs with angles of 0 or 360 degrees or a radius of 0 are
not accepted.
<p>
Example for text input:
<pre>
GRID inch 1;
ARC CW (0 1) (0 -1) (1 0);
</pre>
generates a 90-degree arc with the center at the origin.
<a name=31>
<h1>ASSIGN</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Modify key assignments.
<dt>
<b>Syntax</b>
<dd>
<tt>ASSIGN</tt><br>
<tt>ASSIGN function_key command..;</tt><br>
<tt>ASSIGN function_key;</tt>
<p>
<tt>function_key = modifier+key</tt><br>
<tt>modifier = </tt>any combination of <tt>S</tt> (Shift), <tt>C</tt> (Control), <tt>A</tt> (Alt) and <tt>M</tt> (Cmd, Mac OS X only)<br>
<tt>key = F1..F12, A-Z, 0-9, BS</tt> (Backspace)
</dl>
<b>See also</b> <a href=#91>SCRIPT</a>,
<a href=#19>Keyboard and Mouse</a>
<p>
The ASSIGN command can be used to define the meaning of the function keys
<tt>F1</tt> thru <tt>F12</tt>, the letter keys <tt>A</tt> thru <tt>Z</tt>,
the (upper) digit keys <tt>0</tt> thru <tt>9</tt> and the <tt>backspace</tt>
key (each also in combination with modifier keys).
<p>
The ASSIGN command without parameters displays the present key
assignments in a dialog, which also allows you to modify these settings.
<p>
Keys can be assigned a single command or multiple commands. The command
sequence to be assigned should be enclosed in apostrophes.
<p>
If <tt>key</tt> is one of <tt>A-Z</tt> or <tt>0-9</tt>,
the <tt>modifier</tt> must contain at least <tt>A</tt>, <tt>C</tt> or <tt>M</tt>.
<table><tr><td valign="top"><img src="platforms-mac.png"></td><td valign="middle">
The <b><tt>M</tt></b> modifier is only available on <b>Mac OS X</b>.
</td></tr></table>
<p>
Please note that any special operating system function assigned to a function
key will be overwritten by the ASSIGN command
(depending on the operating system, ASSIGN may not be able to overwrite
certain function keys).<br>
If you assign to a letter key together with the modifier <tt>A</tt>,
(e.g. <tt>A+F</tt>), a corresponding hotkey from the pulldown menu is
no longer available.
<p>
To remove an assignment from a key you can enter <tt>ASSIGN</tt>
with only the function_key code, but no command.
<h2>Examples</h2>
<pre>
ASSIGN F7 'change layer top; route';
ASS A+F7 'cha lay to; rou';
ASSIGN C+F10 menu add mov rou ''';''' edit;
ASSIGN CA+R 'route';
</pre>
The first two examples have the same effect, since EAGLE allows abbreviations
not only with commands but also with parameters (as long as they are
unmistakable).
<p>
Please note that here, for instance, the change layer top command
is terminated by a semicolon, but not the route command. The
reason is that in the first case the command already contains all
the necessary parameters, while in the second case coordinates still
have to be added (usually with the mouse). Therefore the ROUTE command
must not be deactivated by a semicolon.
<h2>Define Command Menu</h2>
If you want to assign the MENU command to a key, the separator
character in the MENU command (semicolon) has to be enclosed in three
pairs of apostrophes (see the third example). This semicolon will
show up in the new menu.
<h2>Presetting of key assignments</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>F1 HELP</tt> </td><td width=20><td>Help function</td></tr>
<tr><td><tt>Alt+F2 WINDOW FIT</tt> </td><td width=20><td>The whole drawing is displayed</td></tr>
<tr><td><tt>F2 WINDOW;</tt> </td><td width=20><td>Screen redraw</td></tr>
<tr><td><tt>F3 WINDOW 2</tt> </td><td width=20><td>Zoom in by a factor of 2</td></tr>
<tr><td><tt>F4 WINDOW 0.5</tt> </td><td width=20><td>Zoom out by a factor of 2</td></tr>
<tr><td><tt>F5 WINDOW (@);</tt> </td><td width=20><td>Cursor pos. is new center</td></tr>
<tr><td><tt>F6 GRID;</tt> </td><td width=20><td>Grid on/off</td></tr>
<tr><td><tt>F7 MOVE</tt> </td><td width=20><td>MOVE command</td></tr>
<tr><td><tt>F8 SPLIT</tt> </td><td width=20><td>SPLIT command</td></tr>
<tr><td><tt>F9 UNDO</tt> </td><td width=20><td>UNDO command</td></tr>
<tr><td><tt>F10 REDO</tt> </td><td width=20><td>REDO command</td></tr>
<tr><td><tt>Alt+BS UNDO</tt> </td><td width=20><td>UNDO command</td></tr>
<tr><td><tt>Shift+Alt+BS REDO</tt> </td><td width=20><td>REDO command</td></tr>
</table>
<a name=32>
<h1>ATTRIBUTE</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Definition of attributes for parts.
<dt>
<b>Syntax</b>
<dd>
<tt>ATTRIBUTE name [ 'value' ] [ options ]</tt><br>
<tt>ATTRIBUTE part_name attribute_name</tt><br>
<tt>ATTRIBUTE part_name attribute_name 'attribute_value' [ [ orientation ] &#149; ]</tt><br>
<tt>ATTRIBUTE part_name attribute_name DELETE</tt><br>
<tt>ATTRIBUTE * [ name [ 'value' ] ]</tt><br>
<tt>ATTRIBUTE * name DELETE</tt><br>
<tt>ATTRIBUTE &#149;..</tt>
</dl>
<b>See also</b> <a href=#98>TECHNOLOGY</a>,
<a href=#68>NAME</a>,
<a href=#103>VALUE</a>,
<a href=#95>SMASH</a>,
<a href=#99>TEXT</a>
<p>
See the description of <tt>orientation</tt> at <a href=#29>ADD</a>.
<p>
An <i>attribute</i> is an arbitrary combination of a <i>name</i> and a <i>value</i>,
that can be used to specify any kind of information for a given part.
<p>
Attributes can be defined in the library (for individual devices), in the schematic
(for an actual part) or in the board (for an actual element). Attributes defined
on the device level will be used for every part of that device type in the schematic.
In a schematic, additional attributes can be defined for each part, and existing
attributes from the devices can be overwritten with new values (if the attributes
have been defined as <i>variable</i>). An element in the board has all the attributes
of its corresponding part, and can have further attributes of its own.
<h2>Attributes in the Library</h2>
In a library the ATTRIBUTE command can be used to define the attributes of a given
technology variant, using the syntax
<pre>
ATTRIBUTE name [ 'value' ] [ options ]
</pre>
The <tt>name</tt> may consist of any letters, digits, '_', '#' and '-' and may have
any length; the first character must not be '-', though. Names are treated
case insensitive, so PartNo is the same as PARTNO. The <tt>value</tt> may
contain any characters and must be enclosed in single quotes.
<p>
The valid <tt>options</tt> are:
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>delete</tt> </td><td width=20><td>Delete the attribute with the given name from all technology variants (in this case there must be no 'value').</td></tr>
<tr><td><tt>variable</tt></td><td width=20><td>Mark this attribute as <i>variable</i>, so that it can be overwritten in the schematic (this is the default).</td></tr>
<tr><td><tt>constant</tt></td><td width=20><td>Attributes marked as <i>constant</i> cannot be overwritten in the schematic (unless the user insists). If a new attribute is defined for a device and has <i>constant</i> set, this setting is copied to all other technologies as well.</td></tr>
</table>
Options may be abbreviated and are case insensitive.
<p>
An already existing attribute can be switched between <i>variable</i> and
<i>constant</i> without the need to repeat its value, as in
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>ATTRIBUTE ABC '123'</tt> </td><td width=20><td>(variable by default)</td></tr>
<tr><td><tt>ATTRIBUTE ABC constant</tt></td><td width=20><td>(ABC retains its value '123')</td></tr>
</table>
If the value of an attribute is changed, its <i>constant/variable</i> setting
remains unchanged (unless explicitly given).
<p>
The attribute names NAME, PART, GATE, DRAWING_NAME, LAST_DATE_TIME,
PLOT_DATE_TIME and SHEET are not allowed, since they would interfere with
the already existing <a href=#99>text variables</a>. If an attribute
named VALUE is defined, its value will be used to initialize the actual value when
placing a part in a schematic (in case the device set has 'Value On').
<h2>Attributes in the Schematic</h2>
In a schematic, the ATTRIBUTE command can be used to assign attributes to
a part, in which case the value of such an attribute overwrites the value
of the attribute with the same name in the library (if the device has such
an attribute and allows overwriting). A part may also be given attributes
that are not defined in the library at all.
<p>
Selecting the ATTRIBUTE command and clicking on a part shows a dialog in which all
attributes of that part are listed and can be edited.
<p>
For a fully textual definition of an attribute, the following syntax can be used:
<pre>
ATTRIBUTE part_name attribute_name 'attribute_value' orientation &#149;
</pre>
Note that in case of a multi-gate part, actually one of the gates (i.e.
"instances") is selected. When selecting it via a mouse click it is already
clear which gate is meant, while when selecting it via part_name, the full
name consisting of the part and gate name should be given.
While a specific part can only have one attribute with a given name, the
attribute can be attached to any or all of its gates.
If only the part name is given, the first visible gate will be implicitly
selected.
<p>
If no coordinates are given (and the command is terminated with a <tt>';'</tt>),
the behavior depends on whether the given attribute already exists for that
part (either in the device or in the schematic). If the attribute already exists,
only its value will be changed. If it doesn't exist yet, a new attribute with
the given name and value will be placed at the origin of the selected gate of the part.
<p>
To delete an attribute from a part, the command
<pre>
ATTRIBUTE part_name attribute_name DELETE
</pre>
can be used.
<p>
When defining attributes via the command line or a script, use the
<a href=#36>CHANGE</a> DISPLAY command to define which parts of the
attribute (name, value, both or none of these) shall be visible.
<h2>Attributes in the Board</h2>
In a board, attributes can be assigned to elements with the ATTRIBUTE
command, much the same as in schematics. By default elements have all the
attributes that are defined for their part in the schematic (and their
device in the library). Attributes with the same name for a given
element/part pair will always have the same value (through <a href=#341>Forward&amp;Back Annotation</a>).
Elements can have additional attributes that are not present in the
schematic or library.
<h2>Global attributes</h2>
Global attributes can be defined in boards and schematics by using <tt>'*'</tt> as
the part name (which implies that this attribute applies to <i>all</i> parts).
Alternatively global attributes can be defined through the menu option
"Edit/Global attributes...". The global attributes of board and schematic
are handled separately and are not connected via <a href=#341>Forward&amp;Back-Annotation</a>.
<p>
Such an attribute could for instance be the author of a drawing, and can be used
in the title block of a drawing's frame. It will be shown on every schematic sheet
that has a drawing frame that contains a <a href=#99>text variable</a>
with the same name.
<h2>Selecting the layer</h2>
Unlike other commands (like WIRE, for instance), the ATTRIBUTE command keeps track
of its last used layer by itself. This has the advantage of making sure that
attributes are always drawn into the right layer, no matter what layers other
commands draw into. The downside of this is that the usual way of setting the layer
in a script, as in
<pre>
LAYER <i>layer</i>;
WIRE (1 2) (3 4);
</pre>
doesn't work here. The layer needs to be selected while the ATTRIBUTE command is
already active, which can be done like this
<pre>
ATTRIBUTE <i>parameters</i>
LAYER <i>layer</i>
<i>more parameters</i>;
</pre>
Note that the ATTRIBUTE line is <b>not</b> terminated with a <tt>';'</tt>, and
that the LAYER command starts on a new line.<br>
The commands
<pre>
ATTRIBUTE
LAYER <i>layer</i>;
</pre>
set the layer to use with subsequent ATTRIBUTE commands.
<h2>Examples</h2>
First the package and technology has to be selected (in case there is more
than one) and then attributes for that technology can be defined:
<pre>
PACKAGE N;
TECHNOLOGY LS;
ATTRIBUTE PartNo '12345-ABC';
ATTRIBUTE Temp '100K' constant;
ATTRIBUTE Remark 'mount manually';
</pre>
<a name=33>
<h1>AUTO</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Starts the Autorouter
<dt>
<b>Syntax</b>
<dd>
<tt>AUTO;</tt><br>
<tt>AUTO signal_name..;</tt><br>
<tt>AUTO ! signal_name..;</tt><br>
<tt>AUTO &#149;..;</tt><br>
<tt>AUTO FOLLOWME</tt><br>
<tt>AUTO LOAD|SAVE filename;</tt>
</dl>
<b>See also</b> <a href=#94>SIGNAL</a>,
<a href=#89>ROUTE</a>,
<a href=#106>WIRE</a>,
<a href=#81>RATSNEST</a>,
<a href=#92>SET</a>
<p>
The AUTO command activates the integrated
<a href=#131>Autorouter</a>. If signal names
are specified or signals are selected with the mouse, only these signals
are routed. Without parameters the command will try to route all signals.
If a "!" character is specified all signals are routed except the
signals following the "!" character. The "!" character must be the
first parameter and must show up only once.
<p>
The <tt>LOAD</tt> and <tt>SAVE</tt> options can be used to load the Autorouter parameters
from or save them to the given file. If <i>filename</i> doesn't have the extension
<tt>".ctl"</tt> it will be appended automatically.
<p>
Without any parameters (or if no terminating <tt>';'</tt> is given), the AUTO command
opens a dialog in which the parameters that control the routing algorithm can
be configured. The special option <tt>FOLLOWME</tt> opens this dialog in a mode
where only the parameters controlling the <a href=#89>Follow-me router</a>
can be modified.
<h2>Example</h2>
<pre>
AUTO ! GND VCC;
</pre>
In every case the semicolon is necessary as a terminator. A menu for
adjusting the Autorouter control parameters opens if you select AUTO
from the command menu or type in AUTO from the keyboard (followed
by Return key).
<h2>Wildcards</h2>
If a <tt>signal_name</tt> parameter is given, the characters <tt>'*'</tt>, <tt>'?'</tt>
and <tt>'[]'</tt> are <i>wildcards</i> and have the following meaning:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>*</tt> </td><td width=20><td>matches any number of any characters</td></tr>
<tr><td><tt>?</tt> </td><td width=20><td>matches exactly one character</td></tr>
<tr><td><tt>[...]</tt></td><td width=20><td>matches any of the characters between the brackets</td></tr>
</table>
<p>
If any of these characters shall be matched exactly as such, it has to be enclosed
in brackets. For example, <tt>abc[*]ghi</tt> would match <tt>abc*ghi</tt> and not
<tt>abcdefghi</tt>.
<p>
A range of characters can be given as <tt>[a-z]</tt>, which results in any character
in the range <tt>'a'</tt>...<tt>'z'</tt>.
<h2>Polygons</h2>
When the Autorouter is started all <a href=#77>Polygons</a> are
calculated.
<h2>Protocol File</h2>
A protocol file (name.pro) is generated automatically.
<h2>Board Size</h2>
The Autorouter puts a rectangle around all objects in the board
and takes the size of this rectangle as the routing area. Wires
in the Dimension layer are border lines for the
Autorouter. This means you can delimit the route area with closed
lines drawn into this layer with the WIRE command.
<p>
In practice you draw the board outlines into the Dimension layer with
the WIRE command and place the components within this area.
<h2>Signals</h2>
Signals defined with EAGLE's SIGNAL command, polygons, and wires drawn
onto the Top, Bottom, and ROUTE2...15 layers are recognized by the
Autorouter.
<h2>Restricted Areas</h2>
Objects in the layers tRestrict, bRestrict,
and vRestrict are treated as restricted areas for the Top and Bottom
side and for vias respectively.
<p>
If you want the Autorouter not to use a layer, enter "0" into the
preferred direction field.
<h2>Canceling</h2>
If you cancel the Autorouter by clicking on the STOP button, any airwires
that have not yet been routed, are not automatically recalculated.
Use the <a href=#81>RATSNEST</a> command to do this.
<a name=34>
<h1>BOARD</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Converts a schematic into a board.
<dt>
<b>Syntax</b>
<dd>
<tt>BOARD [ grid ]</tt>
</dl>
<b>See also</b> <a href=#47>EDIT</a>
<p>
The command BOARD is used to convert a schematic drawing into a board.
<p>
If the board already exists, it will be loaded into a board window.
<p>
If the board does not exist, you will be asked whether to create that new
board.
If a <tt>grid</tt> is given, the parts on the board will be placed in
the given raster, as in
<pre>
BOARD 5mm
</pre>
which would place the parts in a 5 millimeter raster (default is 50mil).
The number must be given with a unit, and the maximum allowed value
is 10mm.
<p>
The BOARD command will never overwrite an existing board file. To create
a new board file if there is already a file with that name, you have to
<a href=#84>remove</a> that file first.
<h2>Creating a board from a schematic</h2>
The first time you edit a board the program checks if there is a
schematic with the same name in the same directory and gives you the
choice to create the board from that schematic.<br>
If you have opened a schematic window and want to create a board, just
type
<pre>
edit .brd
</pre>
in the editor window's command line.
<p>
All relevant data from the schematic file (name.sch) will be converted to a
board file (name.brd). The new board is loaded automatically as an empty
card with a size of 160x100mm
(<a href=#347>Light edition</a>: 100x80mm).
All packages and connections are shown on the left side
of the board. Supply pins are already connected
(see <a href=#75>PIN</a> command).
<p>
If you need board outlines different to the ones that are generated
by default, simply delete the respective lines and use the
<a href=#106>WIRE</a> command to draw your own outlines into
the <i>Dimension</i> layer. The recommended width for these lines is 0.
<p>
A board file cannot be generated:
<ul>
<li>if there are gates in the schematic from a device
for which no package has been defined (error message: "device
name has no package). Exception: if there are only pins with
Direction "Sup" (supply symbols)
<li>if there are gates in the schematic from a device
for which not all pins have been assigned to related pads of a package
(error message: "device name has unconnected pins"). Exception:
device without pins (e.g. frames)
</ul>
<a name=35>
<h1>BUS</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Draws buses in a schematic.
<dt>
<b>Syntax</b>
<dd>
<tt>BUS [bus_name] &#149; [curve | @radius] &#149;..</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Right</mb> changes the wire bend style (see <a href=#92>SET Wire_Bend</a>).<br>
<mb>Shift+Right</mb> reverses the direction of switching bend styles.<br>
<mb>Ctrl+Right</mb> toggles between corresponding bend styles.
</dl>
<b>See also</b> <a href=#69>NET</a>,
<a href=#68>NAME</a>,
<a href=#92>SET</a>
<p>
The command BUS is used to draw bus connections onto the Bus layer
of a schematic diagram. Bus_name has the following form:
<pre>
SYNONYM:partbus,partbus,..
</pre>
where SYNONYM can be any name.
Partbus is either a simple net name or a bus name range of the following form:
<pre>
Name[LowestIndex..HighestIndex]
</pre>
where the following condition must be met:
<p>
0 &lt;= LowestIndex &lt;= HighestIndex &lt;= 511
<p>
If a name is used with a range, that name must not end with digits, because
it would become unclear which digits belong to the Name and which belong to
the range.
<p>
If a bus wire is placed at a point where there is already another bus
wire, the current bus wire will be ended at that point.
This function can be disabled with "<tt>SET AUTO_END_NET OFF;</tt>",
or by unchecking "Options/Set/Misc/Auto end net and bus".
<p>
If the <i>curve</i> or <i>@radius</i> parameter is given, an arc can be drawn as part of the bus
(see the detailed description in the <a href=#106>WIRE</a> command).
<h2>Bus name examples</h2>
<pre>
A[0..15]
RESET
DB[0..7],A[3..4]
ATBUS:A[0..31],B[0..31],RESET,CLOCK,IOSEL[0..1]
</pre>
If no bus name is used, a name of the form B$1 is automatically allocated.
This name can be changed with the NAME command at any time.
<p>
The line width used by the bus can be defined for example with
<pre>
SET Bus_Wire_Width 40;
</pre>
to be 40 mil. (Default: 30 mil).
<h2>Inverted signals</h2>
The name of an inverted signal ("active low") can be displayed overlined if it
is preceded with an exclamation mark (<tt>'!'</tt>), as in
<pre>
ATBUS:A[0..31],B[0..31],!RESET,CLOCK,IOSEL[0..1]
</pre>
which would result in
<pre>
_____
ATBUS:A[0..31],B[0..31],RESET,CLOCK,IOSEL[0..1]
</pre>
You can find further details about this in the description of the <a href=#99>TEXT</a> command.
<a name=36>
<h1>CHANGE</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Changes parameters.
<dt>
<b>Syntax</b>
<dd>
<tt>CHANGE option &#149; &#149;..</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Ctrl+Right</mb> changes parameter of the group.
</dl>
The CHANGE command is used to change or preset properties of objects.
The objects are clicked on with the mouse after the desired parameters
have been selected from the CHANGE command menu or have been typed
in from the keyboard.
<p>
Parameters adjusted with the CHANGE command remain as preset
properties for objects added later.
<p>
All values in the CHANGE command are used according to the actual grid
unit.
<h2>Change Groups</h2>
When using the CHANGE command with a group, the group is first identified
with the <a href=#54>GROUP</a> command before
entering the CHANGE command with appropriate parameters. The right
button of the mouse is then used to execute the changes.
<h2>What can be changed?</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Layer </td><td width=20><td><tt>CHANGE LAYER name | number</tt></td></tr>
<tr><td>Text </td><td width=20><td><tt>CHANGE TEXT [ text ]</tt></td></tr>
<tr><td>Text height </td><td width=20><td><tt>CHANGE SIZE value</tt></td></tr>
<tr><td>Text line width </td><td width=20><td><tt>CHANGE RATIO ratio</tt></td></tr>
<tr><td>Text font </td><td width=20><td><tt>CHANGE FONT VECTOR | PROPORTIONAL | FIXED</tt></td></tr>
<tr><td>Wire width </td><td width=20><td><tt>CHANGE WIDTH value</tt></td></tr>
<tr><td>Wire style </td><td width=20><td><tt>CHANGE STYLE value</tt></td></tr>
<tr><td>Arc cap </td><td width=20><td><tt>CHANGE CAP ROUND | FLAT</tt></td></tr>
<tr><td>Pad shape </td><td width=20><td><tt>CHANGE SHAPE SQUARE | ROUND | OCTAGON | LONG | OFFSET</tt></td></tr>
<tr><td>Pad/via/smd flags </td><td width=20><td><tt>CHANGE STOP | CREAM | THERMALS | FIRST OFF | ON</tt></td></tr>
<tr><td>Pad/via diameter </td><td width=20><td><tt>CHANGE DIAMETER diameter</tt></td></tr>
<tr><td>Pad/via/hole drill </td><td width=20><td><tt>CHANGE DRILL value</tt></td></tr>
<tr><td>Via layers </td><td width=20><td><tt>CHANGE VIA from-to</tt></td></tr>
<tr><td>Smd dimensions </td><td width=20><td><tt>CHANGE SMD width height</tt></td></tr>
<tr><td>Pin parameters </td><td width=20><td><tt>CHANGE DIRECTION NC | IN | OUT | I/O | OC | HIZ | SUP | PAS | PWR | SUP</tt></td></tr>
<tr><td> </td><td width=20><td><tt>CHANGE FUNCTION NONE | DOT | CLK | DOTCLK</tt></td></tr>
<tr><td> </td><td width=20><td><tt>CHANGE LENGTH POINT | SHORT | MIDDLE | LONG</tt></td></tr>
<tr><td> </td><td width=20><td><tt>CHANGE VISIBLE BOTH | PAD | PIN | OFF</tt></td></tr>
<tr><td> </td><td width=20><td><tt>CHANGE SWAPLEVEL number</tt></td></tr>
<tr><td>Polygon parameters </td><td width=20><td><tt>CHANGE THERMALS OFF | ON</tt></td></tr>
<tr><td> </td><td width=20><td><tt>CHANGE ORPHANS OFF | ON</tt></td></tr>
<tr><td> </td><td width=20><td><tt>CHANGE ISOLATE distance</tt></td></tr>
<tr><td> </td><td width=20><td><tt>CHANGE POUR SOLID | HATCH</tt></td></tr>
<tr><td> </td><td width=20><td><tt>CHANGE RANK value</tt></td></tr>
<tr><td> </td><td width=20><td><tt>CHANGE SPACING distance</tt></td></tr>
<tr><td>Gate parameters </td><td width=20><td><tt>CHANGE SWAPLEVEL number</tt></td></tr>
<tr><td> </td><td width=20><td><tt>CHANGE ADDLEVEL NEXT | MUST | ALWAYS | CAN | REQUEST</tt></td></tr>
<tr><td>Net class </td><td width=20><td><tt>CHANGE CLASS number | name</tt></td></tr>
<tr><td>Package </td><td width=20><td><tt>CHANGE PACKAGE part_name [device_name] | 'device_name' [part_name]</tt></td></tr>
<tr><td>Technology </td><td width=20><td><tt>CHANGE TECHNOLOGY part_name [device_name] | 'device_name' [part_name]</tt></td></tr>
<tr><td>Attribute display </td><td width=20><td><tt>CHANGE DISPLAY OFF | VALUE | NAME | BOTH</tt></td></tr>
<tr><td>Frame parameters </td><td width=20><td><tt>CHANGE COLUMS value</tt></td></tr>
<tr><td> </td><td width=20><td><tt>CHANGE ROWS value</tt></td></tr>
<tr><td> </td><td width=20><td><tt>CHANGE BORDER NONE | BOTTOM | RIGHT | TOP | LEFT | ALL</tt></td></tr>
<tr><td>Label </td><td width=20><td><tt>CHANGE XREF OFF | ON</tt></td></tr>
</table>
<a name=37>
<h1>CIRCLE</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Adds circles to a drawing.
<dt>
<b>Syntax</b>
<dd>
<tt>CIRCLE &#149; &#149;.. [center, circumference]</tt><br>
<tt>CIRCLE width &#149; &#149;..</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Center</mb> selects the layer.
</dl>
<b>See also</b> <a href=#36>CHANGE</a>,
<a href=#106>WIRE</a>
<p>
The CIRCLE command is used to create circles. Circles in the layers
tRestrict, bRestrict, and vRestrict define restricted
areas. They should be defined with a width of 0.
<p>
The width parameter defines the width of the circle's circumference
and is the same parameter as used in the WIRE command. The width can
be changed with the command:
<pre>
CHANGE WIDTH width;
</pre>
where <i>width</i> is the desired value in the current unit.
<p>
A circle defined with a width of 0 will be filled.
<h2>Example</h2>
<pre>
GRID inch 1;
CIRCLE (0 0) (1 0);
</pre>
generates a circle with a radius of 1 inch and the center at the origin.
<a name=38>
<h1>CLASS</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Define and use net classes.
<dt>
<b>Syntax</b>
<dd>
<tt>CLASS</tt><br>
<tt>CLASS number|name</tt><br>
<tt>CLASS number [ name [ width [ clearance [ drill ] ] ] ] [ number:clearance .. ]</tt>
</dl>
<b>See also</b> <a href=#133>Design Rules</a>,
<a href=#69>NET</a>,
<a href=#94>SIGNAL</a>,
<a href=#36>CHANGE</a>
<p>
The CLASS command is used to define or use net classes.
<p>
Without parameters, it offers a dialog in which the net classes can be defined.
<p>
If only a <tt>number</tt> or <tt>name</tt> is given, the net class with the given
number or name is selected and will be used for subsequent NET and SIGNAL commands.
<p>
If both a <tt>number</tt> and a <tt>name</tt> are given, the net class with the
given number will be assigned all the following values and will also be used for
subsequent NET and SIGNAL commands. If any of the parameters following <tt>name</tt>
are omitted, the net class will keep its respective value.
<p>
If <tt>number</tt> is negative, the net class with the absolute value of <tt>number</tt>
will be cleared. The default net class <tt>0</tt> can't be cleared.
<p>
Net class names are handled case insensitive, so SUPPLY would be the same as Supply
or SuPpLy.
<p>
Using several net classes in a drawing increases the time the
Autorouter needs to do its job. Therefore it makes sense to use only as few net
classes as necessary (only the number of net classes actually used by nets or
signals count here, not the number of defined net classes).
<p>
In order to avoid conflicts when CUT/PASTEing between drawings it makes sense
to define the same net classes under the same numbers in all drawings.
<p>
The Autorouter processes signals sorted by their total width requirements (Width
plus Clearance), starting with those that require the most space. The bus router
only routes signals with net class <tt>0</tt>.
<p>
The net class of an existing net/signal can be changed with the CHANGE command.
Any changes made by the CLASS command will not be stored in the UNDO/REDO buffer.
<h2>Width</h2>
The <i>width</i> parameter defines a minimum width that all objects in this
net class must have.
<h2>Clearance</h2>
The <i>clearance</i> parameter defines the minimum clearance between objects
of different signals in this net class and objects in other net classes.
<h2>Drill</h2>
The <i>drill</i> parameter defines a minimum drill size that all objects in this
net class must have (only applies to objects that actually have a drill parameter,
like pads and vias).
<h2>Clearance between net classes</h2>
If a clearance is given in the form <tt>number:clearance</tt>, it defines the
minimum clearance between signals in this net class and signals in the net class
with the given <tt>number</tt>. The command
<pre>
CLASS 3 1:0.6mm 2:0.8mm
</pre>
defines a minimum clearance of 0.6mm between signals in net classes 1 and 3,
and one of 0.8mm between signals in net classes 2 and 3. Note that the numbers in
<tt>number:clearance</tt> must be less than or equal to the number of the net class
itself (<tt>'3'</tt> in the above example), so
<pre>
CLASS 3 1:0.6mm 2:0.8mm 3:0.2mm
</pre>
would also be valid, whereas
<pre>
CLASS 3 1:0.6mm 2:0.8mm 3:0.2mm 4:0.5mm
</pre>
would not be allowed.
<a name=39>
<h1>CLOSE</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Closes an editor window.
<dt>
<b>Syntax</b>
<dd>
<tt>CLOSE</tt>
</dl>
<b>See also</b> <a href=#70>OPEN</a>,
<a href=#47>EDIT</a>,
<a href=#107>WRITE</a>,
<a href=#91>SCRIPT</a>
<p>
The CLOSE command is used to close an editor window. If the drawing you
are editing has been modified you will be prompted whether you wish to
save it.
<p>
This command is mainly used in script files.
<a name=40>
<h1>CONNECT</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Assigns package pads to symbol pins.
<dt>
<b>Syntax</b>
<dd>
<tt>CONNECT</tt><br>
<tt>CONNECT symbol_name.pin_name pad_name..</tt><br>
<tt>CONNECT pin_name pad_name..</tt>
</dl>
<b>See also</b> <a href=#78>PREFIX</a>,
<a href=#70>OPEN</a>,
<a href=#39>CLOSE</a>,
<a href=#91>SCRIPT</a>
<p>
This command is used in the device editing mode in order to define
the relationship between the pins of a symbol and the pads of the
corresponding package in the library. First of all, it is necessary
to define which package is to be used by means of the PACKAGE command.
<p>
If the CONNECT command is invoked without parameters, a dialog is
presented which allows you to interactively assign the connections.
<h2>Device with one Symbol</h2>
If only one symbol is included in a device, the parameter symbol_name
can be dropped, e.g.:
<pre>
CONNECT gnd 1 rdy 2 phi1 3 !irq 4 nc1 5...
</pre>
(Note: "!" is used to indicate inverted data signals.)
<h2>Device with Several Symbols</h2>
If several symbols are present in a device, parameters must be entered
with symbol_name, pin_name and pad_name each time. For example:
<pre>
CONNECT A.I1 1 A.I2 2 A.O 3;
CONNECT B.I1 4 B.I2 5 B.O 6;
CONNECT C.I1 13 C.I2 12 C.O 11;
CONNECT D.I1 10 D.I2 9 D.O 8;
CONNECT PWR.gnd 7;
CONNECT PWR.VCC 14;
</pre>
In this case, the connections for four NAND gates of a good old 7400
are allocated. The device includes five symbols - A, B, C, D,
and PWR. The gate inputs are named I1 and I2 while the output is named O.
<p>
The CONNECT command can be repeated as often as required. It may be
used with all pin/pad connections or with only certain pins. Each
new CONNECT command overwrites the previous conditions for the relevant
pins.
<h2>Gate or Pin names that contain periods</h2>
If a gate or pin name contains a period, simply enter them without any special
consideration (no quoting or escape characters are necessary).
<h2>Example</h2>
<pre>
ed 6502.dev;
prefix 'IC';
package dil40;
connect gnd 1 rdy 2 phi1 3 !irq 4 nc1 5 !nmi 6 \
sync 7 vcc 8 a0 9 a1 10 a2 11 a3 12 a4 \
13 a5 14 a6 15 a7 16 a8 17 a9 18 a10 19 \
a11 20 p$0 21 a12 22 a13 23 a14 24 a15 \
25 d7 26 d6 27 d5 28 d4 29 d3 30 d2 31 \
d1 32 d0 33 r/w 34 nc2 35 nc3 36 phi0 37 \
so 38 phi2 39 !res 40;
</pre>
If a command is continued at the next line, it is advisable to
insert the character "\" at the end of the line to ensure
the following text cannot be confused with an EAGLE command.
<p>
Confusing parameters with commands can also be avoided
by enclosing the parameters in apostrophes.
<a name=41>
<h1>COPY</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Copy objects.
<dt>
<b>Syntax</b>
<dd>
<tt>COPY &#149; &#149;..</tt><br>
<tt>COPY deviceset@library [name]</tt><br>
<tt>COPY package@library [name]</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Ctrl+Left</mb> selects an object at its origin.<br>
<mb>Ctrl+Right</mb> selects the group.<br>
<mb>Center</mb> mirrors the selected object or the group.<br>
<mb>Right</mb> rotates the selected object or the group.<br>
<mb>Shift+Right</mb> reverses the direction of rotating.
</dl>
<b>See also</b> <a href=#54>GROUP</a>,
<a href=#42>CUT</a>,
<a href=#74>PASTE</a>,
<a href=#29>ADD</a>,
<a href=#58>INVOKE</a>,
<a href=#77>POLYGON</a>
<p>
The COPY command is used to copy objects
within the same drawing. EAGLE will generate a new name for the
copy but will retain the old value. When copying signals (wires),
buses, and nets the names are retained, but in all other cases a new
name is assigned.
<h2>Copy Wires</h2>
If you copy wires or polygons, belonging to a signal, the
copy will belong to the same signal. Please note, for this reason,
if two wires overlap after the use of the COPY command, the DRC will
not register an error. If a net or bus wire is copied in a schematic,
it belongs to the same segment as the original wire, even if there is
no visible connection. This can lead to unexpected effects, for instance
when renaming them later. Therefore COPY should not be used with
net or bus wires, respectively.
<h2>Copy Parts</h2>
When copying a part in a schematic, there will always be a new instance
of the complete part added, even if only a single gate of a multi-gate
part is selected. In addition to the selected gate, any other gates of that
device which have Add-Level MUST or ALWAYS will automatically be invoked.
<p>
If you just want to use another gate of a multi-gate part, you should use
the <a href=#58>INVOKE</a> command instead.
<h2>Copy library objects</h2>
By writing <tt>COPY deviceset@library</tt> or <tt>COPY package@library</tt>
you can copy a device set or a package from a given library into the currently
loaded library. If an additional <tt>name</tt> is given, the copied object will
be given that name.
This can also be done through the library objects'
<a href=#13>context menu</a> or via <i>Drag&amp;Drop</i> from
the Control Panel's tree view.
<p>
<b>Note that any existing library objects (device sets, symbols or packages)
used by the copied library object will be automatically updated.</b>
<h2>Copy a group</h2>
Copying a group by selecting it with the right mouse button is actually
done by doing an implicit <a href=#42>CUT</a> operation, immediately
followed by a <a href=#74>PASTE</a>.
<a name=42>
<h1>CUT</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Loads a group into the paste buffer.
<dt>
<b>Syntax</b>
<dd>
<tt>CUT &#149;</tt><br>
<tt>CUT;</tt>
</dl>
<b>See also</b> <a href=#74>PASTE</a>,
<a href=#54>GROUP</a>
<p>
Parts of a drawing (or even a whole board) can be copied onto other
drawings by means of the commands CUT and PASTE.
<p>
To do this you first define a group (GROUP command). Then use the
CUT command, followed by a reference point (mouse click or coordinates
(x y)) to put the selected objects into the buffer.
<tt>CUT;</tt> automatically puts the reference point at the center of
the selected objects (snapped to the grid).
Now you can change to another board or package library (EDIT) and
copy the contents of the buffer onto the new drawing by executing
the PASTE command.
<h2>Reference Point</h2>
If you click the mouse after selecting the CUT command, the position
of the mouse cursor defines a reference point for the group, i.e.
when using the PASTE command, the mouse cursor will be at the exact
position of the group.
<h2>Note</h2>
Unlike other (Windows-) programs EAGLE's CUT command does not physically
remove the marked group from the drawing; it only copies the group into
the paste buffer.
<a name=43>
<h1>DELETE</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Deletes objects.
<dt>
<b>Syntax</b>
<dd>
<tt>DELETE &#149;..</tt><br>
<tt>DELETE name ..</tt><br>
<tt>DELETE SIGNALS</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Shift+Left</mb> deletes higher level object.<br>
<mb>Ctrl+Left</mb> deletes a wire joint.<br>
<mb>Ctrl+Right</mb> deletes the group.
</dl>
<b>See also</b> <a href=#87>RIPUP</a>,
<a href=#46>DRC</a>,
<a href=#54>GROUP</a>
<p>
The DELETE command is used to delete the selected object.
<p>
Parts, pads, smds, pins and gates can also be selected by their name,
which is especially useful if the object is outside the currently shown
window area. Note that when selecting a multi-gate part in a schematic by name,
you will need to enter the full instance name, consisting of part
and gate name.
<p>
Attributes of parts can be selected by entering the concatenation of
part name and attribute name, as in <tt>R5&gt;VALUE</tt>.
<p>
Clicking the right mouse button deletes a previously defined
<a href=#54>GROUP</a>.
<p>
After deleting a group it is possible that airwires which have been newly
created due to the removal of a component may be "left over", because
they have not been part of the original group. In such a case you should
re-calculate the airwires with the <a href=#81>RATSNEST</a>
command.
<p>
With active <a href=#341>Forward&amp;Back Annotation</a>, no wires
or vias can be deleted from a signal that is connected to components in a board.
Also, no components can be deleted that have signals connected to them.
Modifications like these have to be done in the schematic.
<p>
Use the <a href=#87>RIPUP</a> command to convert an already
routed connection back into an airwire.
<p>
The DELETE command has no effect on layers that are not visible (refer
to DISPLAY).
<p>
The DRC might generate error polygons which can only be deleted
with DRC CLEAR.
<h2>Deleting Wire Joints</h2>
If the DELETE command, with the <tt>Ctrl</tt> key pressed, is applied to the joining
point of two wires, these wires are combined to form one straight wire.
For this to work the two wires must be in the same layer and have the same width
and line style, and must both have round endings (in case of arcs).
<h2>Deleting Polygon Corners</h2>
The DELETE command deletes one corner at a time from a polygon. The
whole polygon is deleted if there are only three corners left.
<h2>Deleting Components</h2>
Components can be deleted only if the tOrigins layer (or bOrigins with
mirrored components) is visible and if (with active
<a href=#341>Forward&amp;Back Annotation</a>) no signals are
connected to
the component (see also <a href=#86>REPLACE</a>).
Please note that an element may appear to be not connected (no airwires
or wires leading to any of it's pads), while in fact it <b>is</b>
connected to a supply voltage through an implicit power pin. In such a case
you can only delete the corresponding part in the schematic.
<h2>Deleting Junctions, Nets, and Buses</h2>
The following rules apply:
<ul>
<li>If a bus is split into two parts, both keep the initial name.
<li>If a net is split into two parts, the larger one keeps the initial
name while the smaller one gets a new (generated) name.
<li>After the DELETE command, labels belong to the segment next to them.
<li>If a junction point is deleted, the net is separated at this location.
Please check the names of the segments with the SHOW command.
</ul>
<h2>Deleting Supply Symbols</h2>
If the last supply symbol of a given type is deleted from a net segment
that has the same name as the deleted supply pin, that segment is given
a newly generated name (if there are no other supply symbols still
attached to that segment) or the name of one of the remaining supply symbols.
<h2>Deleting Signals</h2>
If you select wires (tracks) or vias belonging to a signal with the DELETE
command three cases have to be considered:
<ul>
<li>The signal is split into two parts. EAGLE will generate a new name
for the smaller part of the signal and keep the previous name for
the larger one.
<li>The signal is deleted from one end. The remaining part of the signal
will keep the previous name.
<li>The signal had only one airwire. It will be deleted completely
and its name won't exist any longer.
</ul>
After wires or vias have been deleted from a signal which contains
polygons, all polygons belong to the signal keeping the original name
(usually the bigger part).
<h2>Deleting all Signals</h2>
<p>
DELETE SIGNALS can be used to delete all signals on a board. This
is useful if you want to read in a new or changed netlist (see EXPORT).
Only those signals are deleted which are connected to pads.
<p>
If you want to delete a part that has the name SIGNALS, you need to
write the name in single quotes.
<h2>Deleting higher level objects</h2>
If the <tt>Shift</tt> key is pressed when clicking on an object, the object
that is hierarchically above the selected one will be deleted. This applies
to the following objects:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>Gate</tt> </td><td width=20><td>Deletes the entire part containing this gate (even if the gates are spread over several sheets). If f/b annotation is active, the wires connected to the element in the board will not be ripped up (as opposed to deleting a single gate), except for those cases where a pin of the deleted part is only connected directly to one single other pin and no net wire</td></tr>
<tr><td><tt>Polygon&nbsp;Wire</tt> </td><td width=20><td>Deletes the entire polygon</td></tr>
<tr><td><tt>Net/Bus&nbsp;Wire</tt> </td><td width=20><td>Deletes the entire net or bus segment</td></tr>
</table>
<p>
Don't forget: Deleting can be reversed by the
<a href=#100>UNDO</a> command!
<a name=44>
<h1>DESCRIPTION</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Defines the description of a device, package or library.
<dt>
<b>Syntax</b>
<dd>
<tt>DESCRIPTION</tt><br>
<tt>DESCRIPTION description_string;</tt>
</dl>
<b>See also</b> <a href=#40>CONNECT</a>,
<a href=#72>PACKAGE</a>,
<a href=#103>VALUE</a>
<p>
This command is used in the library editor to define or edit the description
of a device, package or library.
<p>
The <tt>description_string</tt> may contain <a href=#339>HTML</a> tags.
<p>
The first non-blank line of <tt>description_string</tt> will be used as a short
descriptive text (<i>headline</i>) in the Control Panel.
<p>
The DESCRIPTION command without a parameter opens a dialog in which the text can
be edited. The upper pane of this dialog shows the formatted text, in case it
contains <a href=#339>HTML</a> tags, while the lower pane is used
to edit the raw text. At the very top of the dialog the <i>headline</i> is displayed
as it would result from the first non-blank line of the description. The headline
is stripped of any HTML tags.
<p>
The description of a library can be defined or modified via the command line only if the library is
newly opened, and no device, symbol or package has been edited yet. It can always be
defined via the pulldown menu "Library/Description...".<br>
The description of a device set or package can always be edited via the command line,
or via the pulldown menu "Edit/Description...".
<h2>Example</h2>
<pre>
DESCRIPTION '&lt;b&gt;Quad NAND&lt;/b&gt;&lt;p&gt;\nFour NAND gates with 2 inputs each.';
</pre>
This would result in
<p>
<b>Quad NAND</b><p>
Four NAND gates with 2 inputs each.
<a name=45>
<h1>DISPLAY</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Selects the visible layers.
<dt>
<b>Syntax</b>
<dd>
<tt>DISPLAY</tt><br>
<tt>DISPLAY [option] layer_number..</tt><br>
<tt>DISPLAY [option] layer_name..</tt>
</dl>
<b>See also</b> <a href=#61>LAYER</a>,
<a href=#79>PRINT</a>
<p>
Valid options are: ALL, NONE, LAST, ? and ??
<p>
The DISPLAY command is used to choose the visible layers. As parameters,
the layer number and the layer name are allowed (even mixed). If the
parameter ALL is chosen, all layers become visible. If the parameter
NONE is used, all layers are switched off. For example:
<pre>
DISPLAY NONE BOTTOM;
</pre>
Following this command only the Bottom layer is displayed.
<p>
If the parameter LAST is given, the previously visible layers will be displayed.
<p>
Please note that only those signal layers (1 through 16) are available
that have been entered into the layer setup in the <a href=#133>Design Rules</a>.
<p>
If the layer name or the layer number includes a negative sign, it
will be filtered out. For example:
<pre>
DISPLAY TOP -BOTTOM -3;
</pre>
In this case the Top layer is displayed while the Bottom layer and
the layer with the number 3 are not shown on the screen.
<p>
Avoid layer names ALL and NONE as well as names starting with a "-".
<p>
Some commands (PAD, SMD, SIGNAL, ROUTE) automatically activate certain
layers.
<p>
If t/bPlace is selected or deselected in the DISPLAY menu, the layers
t/bNames, t/bValues, and t/bOrigins are selected or deselected, too.
If Symbols is selected/deselected, the layers Names and Values are
selected/deselected, too.
<p>
If the DISPLAY command is invoked without parameters, a dialog is
presented which allows you to adjust all layer settings.
<h2>Undefined Layers</h2>
The options '?' and '??' can be used to control what happens if an undefined
layer is given in a DISPLAY command. Any undefined layers following a '?' will
cause a warning and the user can either accept it or cancel the entire DISPLAY
command. Undefined layers following a '??' will be silently ignored.
This is most useful for writing script files that shall be able to handle any drawing,
even if a particular drawing doesn't contain some of the listed layers.
<pre>
DISPLAY TOP BOTTOM ? MYLAYER1 MYLAYER2 ?? OTHER WHATEVER
</pre>
In the above example the two layers TOP and BOTTOM are required and will cause
an error if either of them is missing. MYLAYER1 and MYLAYER2 will just be reported
if missing, allowing the user to cancel the operation, and OTHER and WHATEVER will
be displayed if they are there, otherwise they will be ignored.
<p>
The '?' and '??' options may appear any number of times and in any sequence.
<h2>Pads and Vias</h2>
If pads or vias have different shapes on different layers, the shapes of the currently
visible (activated with DISPLAY) signal layers are displayed on top of each other.
<p>
If the color selected for layer 17 (Pads) or 18 (Vias) is 0 (which represents
the current background color), the pads and vias are displayed
in the color and fill style of the respective signal layers. If no signal layer is
visible, pads and vias are not displayed.
<p>
If the color selected for layer 17 (Pads) or 18 (Vias) is not the background
color and no signal layers are visible, pads and vias are displayed in the
shape of the uppermost and undermost layer.
<p>
This also applies to printouts made with <a href=#79>PRINT</a>.
<h2>Selecting Objects</h2>
If you want to select certain objects or elements (e.g.
with MOVE or DELETE) the corresponding layer must be visible. Elements
can only be selected if the tOrigins (or bOrigins with mirrored elements)
layer is visible!
<h2>Parameter Aliases</h2>
Parameter aliases can be used to define certain parameter settings to the
DISPLAY command, which can later be referenced by a given name.
The aliases can also be accessed by clicking on the DISPLAY button
and holding the mouse button pressed until the list pops up.
A right click on the button also pops up the list.
<p>
The syntax to handle these aliases is:
<dl>
<dt>
<tt>DISPLAY = <i>name</i> <i>parameters</i></tt>
<dd>
Defines the alias with the given <i>name</i> to expand to the given
<i>parameters</i>. The <i>name</i> may consist of any number of letters,
digits and underlines, and is treated case insensitive. It must begin
with a letter or underline and may not be one of the option keywords.
<dt>
<tt>DISPLAY = <i>name</i> @</tt>
<dd>
Defines the alias with the given <i>name</i> to expand to the current
parameter settings of the command.
<dt>
<tt>DISPLAY = ?</tt>
<dd>
Asks the user to enter a name for defining an alias for the current
parameter settings of the command.
<dt>
<tt>DISPLAY = <i>name</i></tt>
<dd>
Opens the DISPLAY dialog and allows the user to select a set
of layers that will be defined as an alias under the given <i>name</i>.
<dt>
<tt>DISPLAY = <i>name</i>;</tt>
<dd>
Deletes the alias with the given <i>name</i>.
<dt>
<tt>DISPLAY <i>name</i></tt>
<dd>
Expands the alias with the given <i>name</i> and executes the DISPLAY command with
the resulting set of parameters. The <i>name</i> may be abbreviated and
there may be other parameters before and after the alias (even other
aliases). Note that in case <i>name</i> is an abbreviation, aliases have precedence
over other parameter names of the command.
</dl>
Example:
<p>
<tt>DISPLAY = MyLayers None Top Bottom Pads Vias Unrouted</tt>
<p>
Defines the alias "MyLayers" which, when used as in
<p>
<tt>DISPLAY myl</tt>
<p>
will display just the layers Top, Bottom, Pads, Vias and Unrouted
(without the "None" parameter the given layers would be displayed in
addition to the currently visible layers).
Note the abbreviated use of the alias and the case insensitivity.
<a name=46>
<h1>DRC</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Checks design rules.
<dt>
<b>Syntax</b>
<dd>
<tt>DRC</tt><br>
<tt>DRC &#149; &#149; ;</tt><br>
<tt>DRC LOAD|SAVE filename;</tt>
</dl>
<b>See also</b> <a href=#133>Design Rules</a>,
<a href=#38>CLASS</a>,
<a href=#92>SET</a>,
<a href=#48>ERC</a>,
<a href=#49>ERRORS</a>
<p>
The command DRC checks a board against the current set of <a href=#133>Design Rules</a>.
<p>
Please note that electrically irrelevant objects (wires in packages, rectangles, circles
and texts) are not checked against each other for clearance errors.
<p>
The errors found are displayed as error polygons in the respective layers,
and can be browsed through with the <a href=#49>ERRORS</a> command.
<p>
Without parameters the DRC command opens a Design Rules dialog in which the board's
Design Rules can be defined, and from which the actual check can be started.
<p>
If two coordinates are given in the DRC command (or if the Select button is
clicked in the Design Rules dialog) all checks will be performed solely in the
defined rectangle. Only errors that occur (at least partly) in this area will be reported.
<p>
If you get DRC errors that don't go away, even if you modify the
<a href=#133>Design Rules</a>, make sure you check the
<a href=#38>Net class</a> of the reported object to see whether
the error is caused by a specific parameter of that class.
<p>
To delete all error polygons use the command
<pre>
ERRORS CLEAR
</pre>
<p>
The <tt>LOAD</tt> and <tt>SAVE</tt> options can be used to load the Design Rules
from or save them to the given file. If <i>filename</i> doesn't have the extension
<tt>".dru"</tt> it will be appended automatically.
<h2>Related SET commands</h2>
The SET command can be used to change the behavior of the DRC command:
<pre>
SET DRC_FILL fill_name;
</pre>
Defines the fill style used for the DRC error polygons.
Default is LtSlash.
<a name=47>
<h1>EDIT</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Loads an existing drawing to be edited or creates a new drawing.
<dt>
<b>Syntax</b>
<dd>
<tt>EDIT name</tt><br>
<tt>EDIT name.ext</tt><br>
<tt>EDIT .ext</tt><br>
<tt>EDIT .sX [ .sY ]</tt>
</dl>
<b>See also</b> <a href=#70>OPEN</a>,
<a href=#39>CLOSE</a>,
<a href=#34>BOARD</a>
<p>
The EDIT command is used to load a drawing or if a library has been
opened with the OPEN command, to load a package, symbol, or device for
editing.
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>EDIT name.brd</tt> </td><td width=20><td>loads a board</td></tr>
<tr><td><tt>EDIT name.sch</tt> </td><td width=20><td>loads a schematic</td></tr>
<tr><td><tt>EDIT name.pac</tt> </td><td width=20><td>loads a package</td></tr>
<tr><td><tt>EDIT name.sym</tt> </td><td width=20><td>loads a symbol</td></tr>
<tr><td><tt>EDIT name.dev</tt> </td><td width=20><td>loads a device</td></tr>
<tr><td><tt>EDIT .s3</tt> </td><td width=20><td>loads sheet 3 of a schematic</td></tr>
<tr><td><tt>EDIT .s5 .s2 </tt> </td><td width=20><td>moves sheet 5 before sheet 2 and loads it (if sheet 5 doesn't exist, a new sheet is inserted before sheet 2)</td></tr>
<tr><td><tt>EDIT .s2 .s5 </tt> </td><td width=20><td>moves sheet 2 before sheet 5 and loads it (if sheet 5 doesn't exist, sheet 2 becomes the last sheet)</td></tr>
</table>
<p>
Wildcards in the name are allowed (e.g. *.brd).
<p>
The EDIT command without parameters will cause a
file dialog (in board or schematic mode) or a
<a href=#23>popup menu</a> (in library mode) to appear
from which you can select the file or object.
<p>
To change from schematic to a board with the same name the command
<pre>
EDIT .brd
</pre>
can be used. In the same way to change from board to schematic use
the command
<pre>
EDIT .sch
</pre>
To edit another sheet of a schematic the command
<pre>
EDIT .sX
</pre>
(X is the sheet number) or the combo box in the action toolbar of the
editor window can be used. If the given sheet number doesn't exist,
a new sheet is created.
<p>
You can also switch between sheets by clicking on an icon of the sheet
thumbnail preview. Drag&amp;drop in the thumbnail preview allows you to
reorder sheets. Note that adding, removing or reordering sheets clears
the undo buffer, while simply switching between existing sheets doesn't.
<p>
Symbols, devices or packages may only be edited if a library is first
opened with the OPEN command.
<h2>Which Directory?</h2>
EDIT loads files from the
<a href=#14>project directory</a>.
<a name=48>
<h1>ERC</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Electrical Rule Check.
<dt>
<b>Syntax</b>
<dd>
<tt>ERC</tt>
</dl>
<b>See also</b> <a href=#46>DRC</a>,
<a href=#49>ERRORS</a>,
<a href=#342>Consistency Check</a>
<p>
This command is used to test schematics for electrical errors. The
result of the check is presented in the <a href=#49>ERRORS</a>
dialog.
<h2>Consistency Check</h2>
The ERC command also performs a
<a href=#342>Consistency Check</a>
between a schematic and its corresponding board, provided the board file
has been loaded before starting the ERC.
As a result of this check the automatic
<a href=#341>Forward&amp;Back Annotation</a>
will be turned on or off, depending on whether the files have been found
to be consistent or not.
<p>
Please note that the ERC detects inconsistencies between the implicit power
and supply pins in the schematic and the actual signal connections in the board.
Such inconsistencies can occur if the supply pin configuration is modified
after the board has been created with the BOARD command. Since the power
pins are only connected "implicitly", these changes can't always be forward
annotated.<br>
If such errors are detected, <a href=#341>Forward&amp;Back Annotation</a>
will still be performed, but the supply pin configuration should be checked!
<a name=49>
<h1>ERRORS</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Shows the errors found by the ERC or DRC command.
<dt>
<b>Syntax</b>
<dd>
<tt>ERRORS</tt><br>
<tt>ERRORS CLEAR</tt>
</dl>
<b>See also</b> <a href=#48>ERC</a>,
<a href=#46>DRC</a>
<p>
The command ERRORS is used to show the errors found by the Electrical Rule Check (ERC)
or the Design Rule Check (DRC). If selected, a window is opened in which
all errors are listed. If no ERC or DRC has been run for the loaded drawing, yet,
the respective check will be started first.
<p>
The list view in the ERRORS dialog has up to four sections that contain
<i>Consistency errors</i>, <i>Errors</i>, <i>Warnings</i> and <i>Approved</i>
messages, respectively.
<p>
Selecting an entry with the mouse causes the error to be marked in the editor
window with a rectangle and a line from the upper left corner of the screen.
<p>
Double clicking an entry centers the drawing to the area where the error is located.
Checking the "Centered" checkbox causes this to happen automatically.
<h2>Marking a message as processed</h2>
The <i>Processed</i> button marks a message as processed. It is still contained
in the list, but there is no error indicator in the editor window any more (except
if the list entry is selected). This can be used to mark messages as "done" after
fixing the related problem, without having to run the check again. After the next
ERC/DRC the message will be either gone, or marked as unprocessed again if the
problem still persists.
<h2>Approving a message</h2>
If an error or warning can't be fixed, but apparently doesn't matter (which the
user has to decide), it can be moved to the <i>Approved</i> section by pressing
the <i>Approve</i> button. Messages in that section will not draw error indicators
in the editor window (except if the list entry is selected) and are implicitly
marked as "processed". If any of these messages no longer apply after the
next ERC/DRC, they will be deleted. All approved messages are stored in the drawing
file, so that it is documented which ones have been explicitly approved by the
user. Note that consistency errors can not be approved - they always have to
be fixed in order to activate <a href=#341>Forward&amp;Back Annotation</a>.
<h2>Clearing the list</h2>
The <i>Clear all</i> button deletes all entries form the list, except for the
approved messages. This can be used to get rid of the error indicators in
the editor window. The next ERC/DRC will regenerate the messages again, if
they still apply.
<p>
The list can also be cleared by entering the command
<pre>
ERRORS CLEAR
</pre>
<a name=50>
<h1>EXPORT</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Generation of data files.
<dt>
<b>Syntax</b>
<dd>
<tt>EXPORT SCRIPT filename;</tt><br>
<tt>EXPORT NETLIST filename;</tt><br>
<tt>EXPORT NETSCRIPT filename;</tt><br>
<tt>EXPORT PARTLIST filename;</tt><br>
<tt>EXPORT PINLIST filename;</tt><br>
<tt>EXPORT DIRECTORY filename;</tt><br>
<tt>EXPORT IMAGE filename|CLIPBOARD [MONOCHROME|WINDOW] resolution;</tt>
</dl>
<b>See also</b> <a href=#91>SCRIPT</a>,
<a href=#90>RUN</a>
<p>
The EXPORT command is used to provide you with ASCII text files which
can be used e.g. to transfer data from EAGLE to other programs, or to
generate an image file from the current drawing.
<p>
By default the output file is written into the <b>Project</b> directory.
<p>
The command generates the following output files:
<h2>SCRIPT</h2>
A library previously opened with the OPEN command will be output as
a script file. When a library has been exported and is to be imported
again with the SCRIPT command, a new library should be opened in order
to avoid duplication - e.g. the same symbol is defined more than
once. Reading script files can be accelerated if the command
<pre>
Set Undo_Log Off;
</pre>
is given before.
<h2>NETLIST</h2>
Generates a netlist for the loaded schematic or board. Only nets which
are connected to elements are listed.
<h2>NETSCRIPT</h2>
Generates a netlist for the loaded schematic in the form of a script
file. This file can be used to read a new or changed netlist into
a board where elements have already been placed or previously routed
tracks have been deleted with <tt>DELETE SIGNALS</tt>.
Note that while reading such a script into a board no schematic that
is consistent with this board may be loaded.
<h2>PARTLIST</h2>
Generates a component list for schematics or boards. Only elements
with pins/pads are included.
<h2>PINLIST</h2>
Generates a list with pads and pins, containing the pin directions and
the names of the nets connected to the pins.
<h2>DIRECTORY</h2>
Lists the directory of the currently opened library.
<h2>IMAGE</h2>
Exporting an <i>IMAGE</i> generates an image file with a format corresponding
to the given filename extension. The following image formats are available:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>.bmp</tt></td> <td width=20><td>Windows Bitmap Files</td></tr>
<tr><td><tt>.png</tt></td> <td width=20><td>Portable Network Graphics Files</td></tr>
<tr><td><tt>.pbm</tt></td> <td width=20><td>Portable Bitmap Files</td></tr>
<tr><td><tt>.pgm</tt></td> <td width=20><td>Portable Grayscale Bitmap Files</td></tr>
<tr><td><tt>.ppm</tt></td> <td width=20><td>Portable Pixelmap Files</td></tr>
<tr><td><tt>.tif</tt></td> <td width=20><td>TIFF Files</td></tr>
<tr><td><tt>.xbm</tt></td> <td width=20><td>X Bitmap Files</td></tr>
<tr><td><tt>.xpm</tt></td> <td width=20><td>X Pixmap Files</td></tr>
</table>
<p>
The <i>resolution</i> parameter defines the image resolution (in 'dpi').
<p>
If <i>filename</i> is the special name CLIPBOARD (upper or lowercase doesn't matter)
the image will be copied into the system's clipboard.
<p>
The optional keyword <i>MONOCHROME</i> creates a black&amp;white image.
<p>
The optional keyword <i>WINDOW</i> creates an image of the currently visible
area in the editor window. Without this keyword, the image will contain the
entire drawing.
<a name=51>
<h1>FRAME</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Adds a frame to a drawing.
<dt>
<b>Syntax</b>
<dd>
<tt>FRAME [ columns [ rows ] ] [ borders ] &#149; &#149;</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Center</mb> selects the layer.
</dl>
<b>See also</b> <a href=#60>LABEL</a>
<p>
The FRAME command draws a frame with numbered columns and rows.
The two points define two opposite corners of the frame. Pressing the center
mouse button changes the layer to which the frame is to be added.
<p>
The <tt>columns</tt> parameter defines the number of columns in the frame.
There can be up to 127 columns. By default the columns are numbered from
left to right. If the <tt>columns</tt> value is negative, they are numbered
from right to left.
<p>
The <tt>rows</tt> parameter defines the number of rows in the frame.
There can be up to 26 rows. Rows are marked from top to bottom with letters,
beginning with 'A'. If the <tt>rows</tt> value is negative, they are marked
from bottom to top. If <tt>rows</tt> is given, it must be preceeded by
<tt>columns</tt>.
<p>
The <tt>borders</tt> parameter, if given, defines which sides of the frame
will have a border with numbers or letters displayed. Valid options for this
parameter are <tt>Left</tt>, <tt>Top</tt>, <tt>Right</tt> and <tt>Bottom</tt>.
By default all four sides of the frame will have a border. If any of these
options is given, only the requested sides will have a border. The special
options <tt>None</tt> and <tt>All</tt> can be used to have no borders at all,
or all sides marked.
<p>
Even though you can draw several frames in the same drawing, only the first
one will be used for calculating the positions of parts and nets. These positions
can be used, for instance, in a <a href=#138>User Language</a> Program
to generate a list of parts with their locations in their respective frame.
They are also used internally to automatically generate cross references
for <a href=#60>labels</a>.
<p>
Due to the special nature of the frame object, it doesn't have a rotation of
its own, and it doesn't get rotated with the <a href=#88>ROTATE</a>
command.
<p>
A frame can be drawn directly into a board or schematic, but more typically you
will want to create a special symbol or package drawing that perhaps also
contains a title block, which you can then use in all your drawings.
The "frames" library that comes with EAGLE contains several drawing frames.
<h2>Example</h2>
<pre>
FRAME 10 5 TOP LEFT &#149; &#149;
</pre>
draws a frame with 10 columns (numbered from left to right) and 5 rows (marked
'A' to 'E' from top to bottom) that has the column and row indicators drawn only
at the top and left border.
<a name=52>
<h1>GATESWAP</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Swaps equivalent gates on a schematic.
<dt>
<b>Syntax</b>
<dd>
<tt>GATESWAP &#149; &#149;..;</tt><br>
<tt>GATESWAP gate_name gate_name..;</tt>
</dl>
<b>See also</b> <a href=#29>ADD</a>
<p>
Using this command two gates may be swapped within a schematic. Both
gates must be identical with the same number of pins and must be allocated
the same Swaplevel in the device definition. They do not, however,
need to be in the same device.
<p>
The name used in the GATESWAP command is the displayed name on the
schematic (e.g. U1A for gate A in device U1).
<p>
If a device is not used anymore after the GATESWAP command, it is
deleted automatically from the drawing.
<a name=53>
<h1>GRID</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Defines grid.
<dt>
<b>Syntax</b>
<dd>
<tt>GRID option..;</tt><br>
<tt>GRID;</tt>
<dt>
<b>Keyboard</b>
<dd>
<tt>F6: GRID;</tt> turns the grid on or off.
</dl>
<b>See also</b> <a href=#91>SCRIPT</a>
<p>
The GRID command is used to specify the grid and the current unit.
Given without an option, this command switches between GRID ON
and GRID OFF.
<p>
The following options exist:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>GRID ON;</tt> </td><td width=20><td>Displays the grid on the screen</td></tr>
<tr><td><tt>GRID OFF;</tt> </td><td width=20><td>Turns off displayed grid</td></tr>
<tr><td><tt>GRID DOTS;</tt> </td><td width=20><td>Displays the grid as dots</td></tr>
<tr><td><tt>GRID LINES;</tt> </td><td width=20><td>Displays the grid as solid lines</td></tr>
<tr><td><tt>GRID MIC;</tt> </td><td width=20><td>Sets the grid units to micron</td></tr>
<tr><td><tt>GRID MM;</tt> </td><td width=20><td>Sets the grid units to mm</td></tr>
<tr><td><tt>GRID MIL;</tt> </td><td width=20><td>Sets the grid units to mil</td></tr>
<tr><td><tt>GRID INCH;</tt> </td><td width=20><td>Sets the grid units to inch</td></tr>
<tr><td><tt>GRID FINEST;</tt> </td><td width=20><td>Sets the grid to 0.1 micron</td></tr>
<tr><td><tt>GRID grid_size;</tt> </td><td width=20><td>Defines the distance between</td></tr>
<tr><td> </td><td width=20><td>the grid points in the actual unit</td></tr>
<tr><td><tt>GRID LAST;</tt> </td><td width=20><td>Sets grid to the most recently</td></tr>
<tr><td> </td><td width=20><td>used values</td></tr>
<tr><td><tt>GRID DEFAULT;</tt> </td><td width=20><td>Sets grid to the standard values</td></tr>
<tr><td><tt>GRID grid_size grid_multiple;</tt> </td><td width=20><td></td></tr>
<tr><td> </td><td width=20><td>grid_size = grid distance</td></tr>
<tr><td> </td><td width=20><td>grid_multiple = grid factor</td></tr>
<tr><td><tt>GRID ALT ...;</tt> </td><td width=20><td>Defines the alternate grid</td></tr>
</table>
<h2>Examples</h2>
<pre>
Grid mm;
Set Diameter_Menu 1.0 1.27 2.54 5.08;
Grid Last;
</pre>
In this case you can change back to the last grid definition
although you don't know what the definition looked like.
<pre>
GRID mm 1 10;
</pre>
for instance specifies that the distance between the grid points is
1 mm and that every 10th grid line will be displayed.
<p>
Note: The first number in the GRID command always represents the grid
distance, the second - if existing - represents the grid multiple.
<p>
The GRID command may contain multiple parameters:
<pre>
GRID inch 0.05 mm;
</pre>
In this case the grid distance is first defined as 0.05 inch. Then
the coordinates of the cursor are chosen to be displayed in mm.
<pre>
GRID DEFAULT;
</pre>
Sets grid to the standard value for the current drawing type.
<pre>
GRID mil 50 2 lines on alt mm 1 mil;
</pre>
Defines a 50 mil grid displayed as lines (with only every other line visible), and sets the alternate grid size to 1 mm,
but displays it in mil.
<p>
Pressing the <tt>Alt</tt> key switches to the alternate Grid.
This can typically be a finer grid than the normal one, which allows you to quickly
do some fine positioning in a dense area, for instance, where the normal grid might
be too coarse.
The alternate grid remains active as long as the <tt>Alt</tt> key is held pressed down.
<h2>Parameter Aliases</h2>
Parameter aliases can be used to define certain parameter settings to the
GRID command, which can later be referenced by a given name.
The aliases can also be accessed by clicking on the GRID button
and holding the mouse button pressed until the list pops up.
A right click on the button also pops up the list.
<p>
The syntax to handle these aliases is:
<dl>
<dt>
<tt>GRID = <i>name</i> <i>parameters</i></tt>
<dd>
Defines the alias with the given <i>name</i> to expand to the given
<i>parameters</i>. The <i>name</i> may consist of any number of letters,
digits and underlines, and is treated case insensitive. It must begin
with a letter or underline and may not be one of the option keywords.
<dt>
<tt>GRID = <i>name</i> @</tt>
<dd>
Defines the alias with the given <i>name</i> to expand to the current
parameter settings of the command.
<dt>
<tt>GRID = ?</tt>
<dd>
Asks the user to enter a name for defining an alias for the current
parameter settings of the command.
<dt>
<tt>GRID = <i>name</i></tt>
<dd>
Opens the GRID dialog and allows the user to adjust the grid
parameters and define an alias for them under the given <i>name</i>.
<dt>
<tt>GRID = <i>name</i>;</tt>
<dd>
Deletes the alias with the given <i>name</i>.
<dt>
<tt>GRID <i>name</i></tt>
<dd>
Expands the alias with the given <i>name</i> and executes the GRID command with
the resulting set of parameters. The <i>name</i> may be abbreviated and
there may be other parameters before and after the alias (even other
aliases). Note that in case <i>name</i> is an abbreviation, aliases have precedence
over other parameter names of the command.
</dl>
Example:
<p>
<tt>GRID = MyGrid inch 0.1 lines on</tt>
<p>
Defines the alias "MyGrid" which, when used as in
<p>
<tt>GRID myg</tt>
<p>
will change the current grid to the given settings.
Note the abbreviated use of the alias and the case insensitivity.
<a name=54>
<h1>GROUP</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Defines a group.
<dt>
<b>Syntax</b>
<dd>
<tt>GROUP &#149;..</tt><br>
<tt>GROUP ALL</tt><br>
<tt>GROUP;</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Left&amp;Drag</mb> defines a rectangular group.<br>
<mb>Shift+Left</mb> adds the new group to an existing one.<br>
<mb>Ctrl+Left</mb> toggles the group membership of the selected object.<br>
<mb>Ctrl+Shift+Left</mb> toggles the group membership of the higher level object.<br>
<mb>Right</mb> closes the group polygon.
</dl>
<b>See also</b> <a href=#36>CHANGE</a>,
<a href=#42>CUT</a>,
<a href=#74>PASTE</a>,
<a href=#65>MIRROR</a>,
<a href=#43>DELETE</a>
<p>
The GROUP command is used to define a group of objects
for a successive command. Also a whole drawing or an element can be
defined as a group. Objects are selected - after activating the
GROUP command - by click&amp;dragging a rectangle or by drawing a polygon with the mouse. The easiest
way to close the polygon is to use the right mouse button. Only objects
from displayed layers can become part of the group.
<p>
The keyword <tt>ALL</tt> can be used to define a group that includes
the entire drawing area.
<p>
The group includes:
<ul>
<li>all objects whose origin is inside the polygon
<li>all wires with at least one end point inside the polygon
<li>all circles whose center is inside the polygon
<li>all rectangles with any corner inside the polygon
</ul>
<h2>Move Group</h2>
In order to move a group it is necessary to select the MOVE command
with the right mouse button. When moving wires (tracks) with
the GROUP command that have only one end point in the polygon, this
point is moved while the other one remains at its previous position.
<p>
For instance: In order to change several pad shapes, select
CHANGE and SHAPE with the left mouse button and select the group with
the right mouse button.
<p>
The group definition remains until a new drawing is loaded
or the command
<pre>
GROUP;
</pre>
is executed.
<h2>Extending the group</h2>
If you press the <tt>Shift</tt> key together with any mouse click when
defining the group, the newly defined group will be added to the existing group (if
any).
<h2>Individual objects</h2>
You can toggle the group membership of an individual object by clicking on it
with the <tt>Ctrl</tt> key pressed. If you also press the <tt>Shift</tt> key
when doing so, the group membership of the next higher level object is toggled.
For instance, when clicking on a net wire in a schematic with the GROUP command
and <tt>Ctrl+Shift</tt> pressed, the group membership of the entire segment will
be toggled.
<a name=55>
<h1>HELP</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Help for the current command.
<dt>
<b>Syntax</b>
<dd>
<tt>HELP</tt><br>
<tt>HELP command</tt>
<dt>
<b>Keyboard</b>
<dd>
<tt>F1: HELP</tt> activates the context sensitive help.
</dl>
This command opens a context sensitive help window.
<p>
A <tt>command</tt> name within the HELP command shows the help page of that
command.
<h2>Example</h2>
<pre>
HELP GRID;
</pre>
displays the help page for the GRID command.
<a name=56>
<h1>HOLE</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Add drill hole to a board or package.
<dt>
<b>Syntax</b>
<dd>
<tt>HOLE drill &#149;..</tt>
</dl>
<b>See also</b> <a href=#104>VIA</a>,
<a href=#73>PAD</a>,
<a href=#36>CHANGE</a>
<p>
This command is used to define e.g. mounting holes (has no electrical
connection between the different layers) in a board or in a package.
The parameter drill defines the diameter of the hole in the
actual unit. It may be up to 0.51602 inch (13.1 mm).
<h2>Example</h2>
<pre>
HOLE 0.20 &#149;
</pre>
If the actual unit is "inch", the hole will have a diameter
of 0.20 inch.
<p>
The entered value for the diameter (also used for via-holes and pads)
remains as a presetting for successive operations. It may be changed
with the command:
<pre>
CHANGE DRILL value &#149;
</pre>
A hole can only be selected if the Holes layer is displayed.
<p>
A hole generates a symbol in the Holes layer as well as a circle with
the diameter of the hole in the Dimension layer. The relation between
certain diameters and symbols is defined in the "Options/Set/Drill" dialog.
The circle in the Dimension layer is used by the Autorouter. As
it will keep a (user-defined) minimum distance between via-holes/wires
and dimension lines, it will automatically keep this distance to the
hole.
<p>
Holes generate Annulus symbols in supply layers.
<p>
In the layers tStop and bStop, holes generate the solder
stop mask, whose diameter is determined by the <a href=#133>Design Rules</a>.
<a name=57>
<h1>INFO</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Display and modify object properties.
<dt>
<b>Syntax</b>
<dd>
<tt>INFO &#149;..</tt><br>
<tt>INFO name ..</tt>
</dl>
<b>See also</b> <a href=#36>CHANGE</a>,
<a href=#93>SHOW</a>
<p>
The INFO command displays further details about an object's properties
on screen, e.g. wire width, layer number, text size etc.
It is also possible to modify properties in this dialog.
<p>
Parts, pads, smds, pins and gates can also be selected by their name,
which is especially useful if the object is outside the currently shown
window area. Note that when selecting a multi-gate part in a schematic by name,
you will need to enter the full instance name, consisting of part
and gate name.
<p>
Attributes of parts can be selected by entering the concatenation of
part name and attribute name, as in <tt>R5&gt;VALUE</tt>.
<a name=58>
<h1>INVOKE</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Call a specific symbol from a device.
<dt>
<b>Syntax</b>
<dd>
<tt>INVOKE &#149; orientation &#149;</tt><br>
<tt>INVOKE part_name gate_name orientation &#149;</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Center</mb> mirrors the gate.<br>
<mb>Right</mb> rotates the gate.<br>
<mb>Shift+Right</mb> reverses the direction of rotating.
</dl>
<b>See also</b> <a href=#41>COPY</a>,
<a href=#29>ADD</a>
<p>
See the ADD command for an explanation of Addlevel und Orientation.
<p>
The INVOKE command is used to select a particular gate from a device
which is already in use and place it in the schematic (e.g. a power
symbol with Addlevel = Request).
<p>
Gates are activated in the following way:
<ul>
<li>Enter the part name (e.g. IC5) and select the gate from the popup dialog that appears.
<li>Define device and gate name from the keyboard (e.g. INVOKE IC5 POWER).
<li>Select an existing gate from the device with the mouse and then select the desired gate from the popup menu which appears.
</ul>
The final mouse click positions the new gate.
<p>
If an already invoked gate is selected in the dialog, the default button changes
to "Show", and a click on it zooms the editor window in on the selected gate,
switching to a different sheet if necessary.
<h2>Gates on Different Sheets</h2>
If a gate from a device on a different sheet is to be added
to the current sheet, the name of the gate has to be specified in
the INVOKE command. In this case the right column of the popup menu
shows the sheet number where the already used gates are placed. A
gate placed on the current sheet is indicated by an asterisk.
<a name=59>
<h1>JUNCTION</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Places a dot at intersecting nets.
<dt>
<b>Syntax</b>
<dd>
<tt>JUNCTION &#149;..</tt>
</dl>
<b>See also</b> <a href=#69>NET</a>
<p>
This command is used to draw a connection dot at the intersection
of nets which are to be connected to each other. Junction points may
be placed only on a net. If placed on the intersection of different
nets, the user is given the option to connect the nets.
<p>
If a net wire is placed at a point where there are at least two other
net wires and/or pins, a junction will automatically be placed.
This function can be disabled with "<tt>SET AUTO_JUNCTION OFF;</tt>",
or by unchecking "Options/Set/Misc/Auto set junction".
<p>
On the screen junction points are displayed at least with a diameter
of five pixels.
<a name=60>
<h1>LABEL</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Attaches text labels to buses and nets.
<dt>
<b>Syntax</b>
<dd>
<tt>LABEL [XREF] [orientation] &#149; &#149;..</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Center</mb> selects the layer.<br>
<mb>Right</mb> rotates the label.<br>
<mb>Shift+Right</mb> reverses the direction of rotating.
</dl>
<b>See also</b> <a href=#68>NAME</a>,
<a href=#35>BUS</a>,
<a href=#51>FRAME</a>
<p>
Bus or net names may be placed on a schematic in any location by using
the label command. When the bus or net is clicked on with the mouse,
the relevant label attaches to the mouse cursor and may be rotated,
changed to another layer, or moved to a different location. The second
mouse click defines the location of the label.
<p>
The orientation of the label may be defined textually
using the usual definitions as listed in the <a href=#29>ADD</a> command (R0, R90
etc.).
<p>
Buses and nets may have any number of labels.
<p>
Labels cannot be changed with "CHANGE TEXT".
<p>
Labels are handled by the program as text, but their value corresponds
to the name of the appropriate bus or net. If a bus or net is renamed
with the NAME command, all associated labels are renamed automatically.
<p>
If a bus, net, or label is selected with the SHOW command, all connected
buses, nets and labels are highlighted.
<h2>Cross-reference labels</h2>
If the optional keyword <tt>XREF</tt> is given, the label will be a
"cross-reference" label. Cross-reference labels can be used in multi-sheet
schematics to indicate the next sheet a particular net appears on (note that
this only works for nets, not for busses!).
The <tt>XREF</tt> keyword is mainly for use in scripts. Normally the setting
is taken from what has previously been set with <a href=#36>CHANGE XREF</a>,
or by clicking on the Xref button in the parameter toolbar.
<p>
The format in which a cross-reference label is displayed can be controlled
through the "Xref label format" string, which is defined in the "Options/Set/Misc"
dialog, or with the <a href=#92>SET</a> command.
The following placeholders are defined, and can be used in any order:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>%F</tt></td> <td width=20><td>enables drawing a flag border around the label</td></tr>
<tr><td><tt>%N</tt></td> <td width=20><td>the name of the net</td></tr>
<tr><td><tt>%S</tt></td> <td width=20><td>the next sheet number</td></tr>
<tr><td><tt>%C</tt></td> <td width=20><td>the column on the next sheet</td></tr>
<tr><td><tt>%R</tt></td> <td width=20><td>the row on the next sheet</td></tr>
</table>
<p>
The default format string is <tt>"%F%N/%S.%C%R"</tt>. Apart from the defined
placeholders you can also use any other ASCII characters.
<p>
The column and row values only work if there is a <a href=#51>frame</a>
on the next sheet on which the net appears. If <tt>%C</tt> or <tt>%R</tt> is
used and there is no frame on that sheet, they will display a question mark (<tt>'?'</tt>).
<p>
When determining the column and row of a net on a sheet, first the column and then
the row within that column is taken into account. Here XREF labels take precedence
over normal labels, which again take precedence over net wires.
For a higher sheet number, the frame coordinates of the left- and topmost field
are taken, while for a lower sheet number those of the right- and bottommost field
are used.
<p>
The orientation of a cross-reference label defines whether it will point to
a "higher" or a "lower" sheet number. Labels with an orientation of R0 or R270 point
to the right or bottom border of the drawing, and will therefore refer to
a higher sheet number. Accordingly, labels with an orientation of R90 or R180 will
refer to a lower sheet number. If a label has an orientation of R0 or R270, but the
net it is attached to is not present on any higher sheet, a reference to the next
lower sheet is displayed instead (the same applies accordingly to R90 and R180).
If the net appears only on the current sheet, no cross-reference is shown at all,
and only the net name is displayed (surrounded by the flag border, if the format
string contains the <tt>%F</tt> placeholder).
<p>
A cross-reference label that is placed on the end of a net wire will connect to
the wire so that the wire is moved with the label, and vice versa.
<p>
The cross-reference label format string is stored within the schematic drawing file.
<p>
A cross-reference label can be changed to a normal label either through the
<a href=#36>CHANGE</a> command or the label's <i>Properties</i> dialog.
<h2>Selecting the layer</h2>
Unlike other commands (like WIRE, for instance), the LABEL command keeps track
of its last used layer by itself. This has the advantage of making sure that
labels are always drawn into the right layer, no matter what layers other
commands draw into. The downside of this is that the usual way of setting the layer
in a script, as in
<pre>
LAYER <i>layer</i>;
WIRE (1 2) (3 4);
</pre>
doesn't work here. The layer needs to be selected while the LABEL command is
already active, which can be done like this
<pre>
LABEL <i>parameters</i>
LAYER <i>layer</i>
<i>more parameters</i>;
</pre>
Note that the LABEL line is <b>not</b> terminated with a <tt>';'</tt>, and
that the LAYER command starts on a new line.<br>
The commands
<pre>
LABEL
LAYER <i>layer</i>;
</pre>
set the layer to use with subsequent LABEL commands.
<a name=61>
<h1>LAYER</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Changes and defines layers.
<dt>
<b>Syntax</b>
<dd>
<tt>LAYER layer_number</tt><br>
<tt>LAYER layer_name</tt><br>
<tt>LAYER layer_number layer_name</tt><br>
<tt>LAYER [??] -layer_number</tt>
</dl>
<b>See also</b> <a href=#45>DISPLAY</a>
<h2>Choose Drawing Layer</h2>
The LAYER command with one parameter is used to change the current
layer, i.e. the layer onto which wires, circles etc. will be drawn.
If LAYER is selected from the menu, a popup menu will appear in which
you may change to the desired layer. If entered from the command line,
'layer_number' may be the number of any valid layer, and 'layer_name'
may be the name of a layer as displayed in the popup menu.
<p>
Certain layers are not available in all modes.
<p>
Please note that only those signal layers (1 through 16) are available
that have been entered into the layer setup in the <a href=#133>Design Rules</a>.
<h2>Define Layers</h2>
The LAYER command with two parameters is used to define a new layer
or to rename an existing one.
If you type in at the command prompt e.g.
<pre>
LAYER 101 SAMPLE;
</pre>
you define a new layer with layer number 101 and layer name SAMPLE.
<p>
If a package contains layers not yet specified in the board, these
layers are added to the board as soon as you place the package into
the board (ADD or REPLACE).
<p>
The predefined layers have a special function.
You can change their names, but their functions (related with their
number) remain the same.
<p>
If you define your own layers, you should use only numbers
greater than 100. Numbers below may be assigned for special purposes
in later EAGLE versions.
<h2>Delete Layers</h2>
The LAYER command with the minus sign and a layer_number deletes the
layer with the specified number, e.g.
<pre>
LAYER -103;
</pre>
deletes the layer number 103. Layers to be deleted must be empty.
If this is not the case, the program generates the error message
<p>
"layer is not empty: #"
<p>
where "#" represents the layer number.
If you want to avoid any error messages in a layer delete operation
you can use the '??' option. This may be
useful in scripts that try to delete certain layers, but don't consider
it an error if any of these layers is not empty or not present at all.
<p>
The predefined standard layers cannot be deleted.
<h2>Supply Layers</h2>
Layers 2...15 are treated as <i>supply layers</i> if their name starts with the <tt>'$'</tt>
character and there is a signal with an identical name but without the leading <tt>'$'</tt>.
<p>
Any pads or vias belonging to that signal are implicitly considered connected by the
<a href=#81>RATSNEST</a> command and the <a href=#131>Autorouter</a>.
<p>
Supply layers are viewed "inverted", which means that any objects visible on such a layer
will result in "copper free" areas on the board. The program automatically generates
Thermal and Annulus objects to connect and isolate pads and vias to/from these layers.
<p>
You should not draw any additional objects into a supply layer, except, for instance, wires
along the outlines of the board, which prevent the copper area from extending to the very
edges and thus possibly causing short circuits through a metal casing or mounting screw.
Note that there are <b>no checks whether a supply layer really connects all pads and vias</b>.
If e. g. a user drawn object isolates a pad that should be connected to the supply
layer, there will be no airwire generated for that (missing) connection. The same applies if several
Annulus symbols form a "ring" around a Thermal symbol (and would thus completely isolate
that pad from its signal).
<b>Also note that the size of the annulus symbols used in a supply layer is only
derived from the value given under "Annulus" in the "Supply" tab of the
<a href=#133>Design Rules</a>, and that neither the minimum distances
under "Clearance" nor those in the <a href=#38>net classes</a> go
into this calculation.</b>
<p>
For a safer and more flexible way of implementing supply layers you should use the
<a href=#77>POLYGON</a> command.
<h2>Predefined EAGLE Layers</h2>
<h3>Layout</h3>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>1 Top </td><td width=20><td>Tracks, top side</td></tr>
<tr><td>2 Route2 </td><td width=20><td>Inner layer (signal or supply)</td></tr>
<tr><td>3 Route3 </td><td width=20><td>Inner layer (signal or supply)</td></tr>
<tr><td>4 Route4 </td><td width=20><td>Inner layer (signal or supply)</td></tr>
<tr><td>5 Route5 </td><td width=20><td>Inner layer (signal or supply)</td></tr>
<tr><td>6 Route6 </td><td width=20><td>Inner layer (signal or supply)</td></tr>
<tr><td>7 Route7 </td><td width=20><td>Inner layer (signal or supply)</td></tr>
<tr><td>8 Route8 </td><td width=20><td>Inner layer (signal or supply)</td></tr>
<tr><td>9 Route9 </td><td width=20><td>Inner layer (signal or supply)</td></tr>
<tr><td>10 Route10 </td><td width=20><td>Inner layer (signal or supply)</td></tr>
<tr><td>11 Route11 </td><td width=20><td>Inner layer (signal or supply)</td></tr>
<tr><td>12 Route12 </td><td width=20><td>Inner layer (signal or supply)</td></tr>
<tr><td>13 Route13 </td><td width=20><td>Inner layer (signal or supply)</td></tr>
<tr><td>14 Route14 </td><td width=20><td>Inner layer (signal or supply)</td></tr>
<tr><td>15 Route15 </td><td width=20><td>Inner layer (signal or supply)</td></tr>
<tr><td>16 Bottom </td><td width=20><td>Tracks, bottom side</td></tr>
<tr><td>17 Pads </td><td width=20><td>Pads (through-hole)</td></tr>
<tr><td>18 Vias </td><td width=20><td>Vias (through-hole)</td></tr>
<tr><td>19 Unrouted </td><td width=20><td>Airwires (rubberbands)</td></tr>
<tr><td>20 Dimension </td><td width=20><td>Board outlines (circles for holes)</td></tr>
<tr><td>21 tPlace </td><td width=20><td>Silk screen, top side</td></tr>
<tr><td>22 bPlace </td><td width=20><td>Silk screen, bottom side</td></tr>
<tr><td>23 tOrigins </td><td width=20><td>Origins, top side</td></tr>
<tr><td>24 bOrigins </td><td width=20><td>Origins, bottom side</td></tr>
<tr><td>25 tNames </td><td width=20><td>Service print, top side</td></tr>
<tr><td>26 bNames </td><td width=20><td>Service print, bottom side</td></tr>
<tr><td>27 tValues </td><td width=20><td>Component VALUE, top side</td></tr>
<tr><td>28 bValues </td><td width=20><td>Component VALUE, bottom side</td></tr>
<tr><td>29 tStop </td><td width=20><td>Solder stop mask, top side</td></tr>
<tr><td>30 bStop </td><td width=20><td>Solder stop mask, bottom side</td></tr>
<tr><td>31 tCream </td><td width=20><td>Solder cream, top side</td></tr>
<tr><td>32 bCream </td><td width=20><td>Solder cream, bottom side</td></tr>
<tr><td>33 tFinish </td><td width=20><td>Finish, top side</td></tr>
<tr><td>34 bFinish </td><td width=20><td>Finish, bottom side</td></tr>
<tr><td>35 tGlue </td><td width=20><td>Glue mask, top side</td></tr>
<tr><td>36 bGlue </td><td width=20><td>Glue mask, bottom side</td></tr>
<tr><td>37 tTest </td><td width=20><td>Test and adjustment inf., top side</td></tr>
<tr><td>38 bTest </td><td width=20><td>Test and adjustment inf. bottom side</td></tr>
<tr><td>39 tKeepout </td><td width=20><td>Nogo areas for components, top side</td></tr>
<tr><td>40 bKeepout </td><td width=20><td>Nogo areas for components, bottom side</td></tr>
<tr><td>41 tRestrict </td><td width=20><td>Nogo areas for tracks, top side</td></tr>
<tr><td>42 bRestrict </td><td width=20><td>Nogo areas for tracks, bottom side</td></tr>
<tr><td>43 vRestrict </td><td width=20><td>Nogo areas for via-holes</td></tr>
<tr><td>44 Drills </td><td width=20><td>Conducting through-holes</td></tr>
<tr><td>45 Holes </td><td width=20><td>Non-conducting holes</td></tr>
<tr><td>46 Milling </td><td width=20><td>Milling</td></tr>
<tr><td>47 Measures </td><td width=20><td>Measures</td></tr>
<tr><td>48 Document </td><td width=20><td>General documentation</td></tr>
<tr><td>49 Reference </td><td width=20><td>Reference marks</td></tr>
<tr><td>51 tDocu </td><td width=20><td>Part documentation, top side</td></tr>
<tr><td>52 bDocu </td><td width=20><td>Part documentation, bottom side</td></tr>
</table>
<h3>Schematic</h3>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>91 Nets </td><td width=20><td>Nets</td></tr>
<tr><td>92 Busses </td><td width=20><td>Buses</td></tr>
<tr><td>93 Pins </td><td width=20><td>Connection points for component symbols</td></tr>
<tr><td> </td><td width=20><td>with additional information</td></tr>
<tr><td>94 Symbols </td><td width=20><td>Shapes of component symbols</td></tr>
<tr><td>95 Names </td><td width=20><td>Names of component symbols</td></tr>
<tr><td>96 Values </td><td width=20><td>Values/component types</td></tr>
<tr><td>97 Info </td><td width=20><td>General information</td></tr>
<tr><td>98 Guide </td><td width=20><td>Guide lines</td></tr>
</table>
<a name=62>
<h1>LOCK</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Locks the position and orientation of a part in the board.
<dt>
<b>Syntax</b>
<dd>
<tt>LOCK &#149;..</tt><br>
<tt>LOCK name ..</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Ctrl+Right</mb> applies the command to the group.<br>
<mb>Shift+Left</mb> reverses the lock operation ("unlocks" the part).<br>
<mb>Ctrl+Shift+Right</mb> "unlocks" all parts in the group.
</dl>
<b>See also</b> <a href=#67>MIRROR</a>,
<a href=#67>MOVE</a>,
<a href=#88>ROTATE</a>
<a href=#95>SMASH</a>
<p>
The LOCK command can be applied to parts in a board, and prevents them
from being moved, rotated, or mirrored. This is useful for things like
connectors, which need to be mounted at a particular location and must
not be inadvertently moved.
<p>
The origin of a locked part is displayed as an 'x' to have a visual
indication that the part is locked.
<p>
If a group is moved and it contains locked parts, these parts (together
with any wires ending at their pads) will not move with the group.
<p>
Detached texts of a locked part can still be moved individually, but
they won't move with a group.
<p>
Parts can also be selected by their name,
which is especially useful if the object is outside the currently shown
window area.
<p>
A "locked" part can be made "unlocked" by clicking on it with the
<tt>Shift</tt> key pressed (and of course the LOCK command activated).
<a name=63>
<h1>MARK</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Defines a mark on the drawing area.
<dt>
<b>Syntax</b>
<dd>
<tt>MARK &#149;</tt><br>
<tt>MARK;</tt>
</dl>
<b>See also</b> <a href=#53>GRID</a>
<p>
The MARK command allows you to define a point
on the drawing area and display the coordinates of the mouse cursor relative
to that point at the upper left corner of the screen (with a leading
'R' character). This command is useful especially when board dimensions
or cutouts are to be defined. Entering MARK; turns the mark
on or off.
<p>
Please choose a grid fine enough before using the MARK command.
<a name=64>
<h1>MENU</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Customizes the textual command menu.
<dt>
<b>Syntax</b>
<dd>
<tt>MENU option ..;</tt><br>
<tt>MENU;</tt>
</dl>
<b>See also</b> <a href=#31>ASSIGN</a>,
<a href=#91>SCRIPT</a>
<p>
The MENU command can be used to create a user specific command menu.
<p>
The complete syntax specification for the <tt>option</tt> parameters is
<pre>
option := command | menu | delimiter
command := text [ ':' text ]
menu := text '{' option [ '|' option ] '}'
delimiter := '---'
</pre>
A menu option can either be a simple command, as in
<pre>
MENU Display Grid;
</pre>
which would set the menu to the commands <tt>Display</tt> and <tt>Grid</tt>;
an aliased command, as in
<pre>
MENU 'MyDisp : Display None Top Bottom Pads Vias;' 'MyGrid : Grid mil 100 lines on;';
</pre>
which would set the menu to show the command aliases <tt>MyDisp</tt> and <tt>MyGrid</tt>
and actually execute the command sequence behind the <tt>':'</tt> of each option when
the respective button is clicked;
or a submenu button as in
<pre>
MENU 'Grid { Fine : Grid inch 0.001; | Coarse : Grid inch 0.1; }';
</pre>
which would define a button labelled <tt>Grid</tt> that, when clicked opens a
submenu with the two options <tt>Fine</tt> and <tt>Coarse</tt>.
<p>
The special option <tt>'---'</tt> can be used to insert a delimiter, which
may be useful for grouping buttons.
<p>
Note that any <i>option</i> that consists of more than a single word, or that
might be interpreted as a command, must be enclosed in single quotes.
If you want to use the MENU command in a script to define a complex menu,
and would like to spread the menu definitions over several lines to make
them more readable, you need to end the lines with a backslash character (<tt>'\'</tt>)
as in
<pre>
MENU 'Grid {\
Fine : Grid inch 0.001; |\
Coarse : Grid inch 0.1;\
}';
</pre>
<h2>Example</h2>
<pre>
MENU Move Delete Rotate Route ';' Edit;
</pre>
would create a command menu that contains the commands Move...Route,
the semicolon, and the Edit command.
<p>
The command
<pre>
MENU;
</pre>
switches back to the default menu.
<p>
Note that the ';' entry should always be added
to the menu. It is used to terminate many commands.
<a name=65>
<h1>MIRROR</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Mirrors objects and groups.
<dt>
<b>Syntax</b>
<dd>
<tt>MIRROR &#149;..</tt><br>
<tt>MIRROR name..</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Ctrl+Right</mb> mirrors the group.
</dl>
<b>See also</b> <a href=#88>ROTATE</a>,
<a href=#62>LOCK</a>,
<a href=#99>TEXT</a>
<p>
Using the MIRROR command, objects may be mirrored about the y axis.
One application for this command is to mirror components to be placed
on the reverse side of the board.
<p>
Parts, pads, smds and pins can also be selected by their name,
which is especially useful if the object is outside the currently shown
window area.
<p>
Attributes of parts can be selected by entering the concatenation of
part name and attribute name, as in <tt>R5&gt;VALUE</tt>.
<p>
Components can be mirrored only if the appropriate tOrigins/bOrigins
layer is visible.
<p>
When packages are selected for use with the MIRROR
command, connected wires on the outer layers are mirrored, too (beware of short
circuits!).
<p>
Note that any objects on inner layers (2...15) don't change their layer
when they are mirrored. The same applies to vias.
<p>
Parts cannot be mirrored if they are <a href=#62>locked</a>,
or if any of their connected pads would extend outside the allowed area
(in case you are using a <a href=#347>limited edition</a> of EAGLE).
<h2>Mirror a Group</h2>
In order to mirror a group of elements, the group is first defined
with the GROUP command and polygon in the usual manner. The MIRROR
command is then selected and the right mouse button is used to execute
the change. The group will be mirrored about the vertical axis through
the next grid point.
<p>
Wires, circles, pads and polygons may not be individually
mirrored unless included in a group.
<h2>Mirror Texts</h2>
Text on the solder side of a pc board (Bottom and bPlace layers) is
mirrored automatically so that it is readable when you look at the
solder side of the board.
<p>
Mirrored text in a schematic will be printed on the other side of its origin point,
but it will still remain normally readable.
<a name=66>
<h1>MITER</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Miters wire joints.
<dt>
<b>Syntax</b>
<dd>
<tt>MITER [radius] &#149;..</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Left&amp;Drag</mb> dynamically modifies the miter.<br>
<mb>Right</mb> toggles between round and straight mitering.
</dl>
<b>See also</b> <a href=#97>SPLIT</a>,
<a href=#106>WIRE</a>,
<a href=#89>ROUTE</a>,
<a href=#77>POLYGON</a>
<p>
The MITER command can be used to take the edge off a point where two wires join.
The two existing wires need to be on the the same layer and must have the same
width and wire style.
<h2>Mitering a point</h2>
If you select a point where exactly two straight wires join, an additional wire will
be inserted between these two wires, according to the given <i>radius</i>.
If you click&amp;drag on such a point with the left mouse button, you can define
the mitering wire dynamically.
<h2>Mitering a wire</h2>
If you select a wire (which may also be an arc) somewhere in the middle between its
end points, and that wire is connected to exactly two other straight wires (one at each
end), the selected wire will be "re-mitered" according to the given <i>radius</i>.
If you click&amp;drag on such a wire with the left mouse button, you can define
the mitering wire dynamically.
<h2>Straight versus round mitering</h2>
If <i>radius</i> is positive, the inserted wire will be an arc with the given radius;
if it is negative, a straight wire will be inserted (imagine the <tt>'-'</tt> sign as
indicating "straight"). You can toggle between round and straight mitering by pressing
the right mouse button.
<h2>Miter radius and wire bend style</h2>
The <i>radius</i> you give in the MITER command will be used in all other commands
that draw wires in case the wire bend style is one of the 90 or 45 degree styles.
If you have set round mitering, it will apply to both the 90 and 45 degree bend styles;
in case of straight mitering only the 90 degree bend styles are affected.
<a name=67>
<h1>MOVE</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Moves objects.
<dt>
<b>Syntax</b>
<dd>
<tt>MOVE &#149; &#149;..</tt><br>
<tt>MOVE name &#149;..</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Ctrl+Left</mb> selects an object at its origin or modifies it (see note).<br>
<mb>Ctrl+Right</mb> selects the group.<br>
<mb>Left&amp;Drag</mb> immediately moves the object.<br>
<mb>Ctrl+Right&amp;Drag</mb> immediately moves the group.<br>
<mb>Center</mb> mirrors the selected object or the group.<br>
<mb>Right</mb> rotates the selected object or the group.<br>
<mb>Shift+Right</mb> reverses the direction of rotating.
<dt>
<b>Keyboard</b>
<dd>
<tt>F7: MOVE</tt> activates the MOVE command.
</dl>
<b>See also</b> <a href=#54>GROUP</a>,
<a href=#62>LOCK</a>,
<a href=#81>RATSNEST</a>
<p>
The MOVE command is used to move objects.
<p>
Parts, pads, smds, pins and gates can also be selected by their name,
which is especially useful if the object is outside the currently shown
window area. Note that when selecting a multi-gate part in a schematic by name,
you will need to enter the full instance name, consisting of part
and gate name.
<p>
Attributes of parts can be selected by entering the concatenation of
part name and attribute name, as in <tt>R5&gt;VALUE</tt>.
<p>
Elements can be moved only if the appropriate tOrigins/bOrigins
layer is visible.
<p>
The MOVE command has no effect on layers that are not
visible (refer to DISPLAY).
<p>
The ends of wires (tracks) that are connected to an element cannot
be moved at this point.
<p>
When moving elements, connected wires (tracks) that belong to a signal
are moved too (beware of short circuits!).
<p>
If an object is selected with the left mouse button and the button is
not released, the object can be moved immediately ("click&amp;drag").
The same applies to groups when using the right mouse button.
In this mode, however, it is not possible to rotate or mirror the object
while moving it.
<p>
Parts cannot be moved if they are <a href=#62>locked</a>,
or if any of their connected pads would extend outside the allowed area
(in case you are using a <a href=#347>limited edition</a> of EAGLE).
<h2>Move Wires</h2>
If, following a MOVE command, two wires from different
signals are shorted together, they are maintained as separate signals
and the error will be flagged by the DRC command.
<h2>Move Groups</h2>
In order to move a group, the selected objects are defined in the
normal way (GROUP command and polygon) before selecting the MOVE command
and clicking the group with the right mouse button. The entire group
can now be moved and rotated with the right mouse button.
<h2>Hints for Schematics</h2>
If a supply pin (Direction Sup) is placed on a net, the pin name is
allocated to this net.
<p>
Pins placed on each other are connected together.
<p>
If unconnected pins of an element are placed on nets or pins then
they are connected with them.
<p>
If nets are moved over pins they are not connected with them.
<h2>Selecting objects at their origin</h2>
Normally a selected object remains within the grid it has been originally
placed on. If you press <tt>Ctrl</tt> while selecting an object, the point
where you have selected the object is pulled towards the cursor and snapped into
the current grid.
<p>
If you select a <i>wire</i> somewhere in the middle (not at one of its end points)
with <tt>Ctrl</tt> pressed, the end points stay fixed and you can bend the wire,
which changes it into an arc. The same way the curvature of an arc (which is basically
a wire) can be modified.
<p>
If you select a <i>rectangle</i> at one of its corners with <tt>Ctrl</tt> pressed,
you can resize both the rectangle's width and height. Selecting an edge of the
rectangle with <tt>Ctrl</tt> pressed lets you resize the rectangle's width or height,
respectively. Selecting the rectangle at its center with <tt>Ctrl</tt> pressed
pulls it towards the cursor and snaps it into the current grid.
<p>
If you select a <i>circle</i> at its circumference with <tt>Ctrl</tt> pressed, the
center stays fixed and you can resize the circle's diameter. Selecting the center point
this way pulls it towards the cursor and snaps it into the current grid.
<h2>Move part of a sheet to an other sheet</h2>
You can move part of a sheet to an other sheet of the same schematic without
affecting the board (in case <a href=#341>Forward&amp;Back Annotation</a>
is active) by defining a <a href=#54>GROUP</a> that contains the objects
you want to move, selecting that group with the MOVE command and then switching to
the desired sheet, with the MOVE command still active and having the group attached
to the cursor. In the new sheet the MOVE command will be active again and will have
the previously defined group attached to the cursor. Now place the group as usual,
and all the affected objects will be transferred from the original sheet to the
current sheet. If the current sheet is the same as the original sheet, nothing
happens.
<p>
Note that only wires that have both ends in the group will be transferred, and
any part that is transferred takes all its electrical connections with it, even if
a net wire attached to one of its pins is not transferred because its other end
is not in the group.
In case a pin in the new sheet has an electrical connection, but no other pin,
wire or junction attached to it to make this visible, a junction will be
automatically generated at this point.
<p>
This process can even be scripted. For instance
<pre>
edit .s1
group (1 1) (1 2) (2 2) (2 1) (1 1)
move (&gt; 0 0)
edit .s2
(0 0)
</pre>
would switch to the first sheet, define a group, select that group with MOVE,
switch to the second sheet and place the group. Note the final <tt>(0 0)</tt>,
which are coordinates to the implicitly invoked MOVE command.
<p>
See the <a href=#47>EDIT</a> command if you want to just reorder the
sheets.
<a name=68>
<h1>NAME</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Displays and changes names.
<dt>
<b>Syntax</b>
<dd>
<tt>NAME &#149;..</tt><br>
<tt>NAME new_name &#149;</tt><br>
<tt>NAME old_name new_name</tt>
</dl>
<b>See also</b> <a href=#93>SHOW</a>,
<a href=#95>SMASH</a>,
<a href=#103>VALUE</a>
<p>
The NAME command is used to display or edit the name of the selected object.
<p>
Parts, pads, smds, pins and gates can also be selected by their name,
which is especially useful if the object is outside the currently shown
window area.
<h2>Library</h2>
When in library edit mode, the NAME command is used to display or
edit the name of the selected pad, smd, pin or gate.
<h2>Automatic Naming</h2>
EAGLE generates names automatically: E$.. for elements, S$.. for signals,
P$.. for pads, pins and smds. In general, it is convenient to substitute
commonly used names (e.g. 1...14 for a 14-pin dual inline package)
in place of these automatically generated names.
<h2>Schematic</h2>
If nets or buses are to be renamed, the program has to distinguish
between three cases because they can consist of several segments placed
on different sheets. Thus a menu will ask the user:
<p>
This segment<br>
Every segment on this sheet<br>
All segments on all sheets
<p>
These questions appear in a popup menu if necessary
and can be answered either by selecting the appropriate item with
the mouse or by pressing the appropriate hot key (T, E, A).
<h2>Polygon</h2>
When renaming a signal polygon in a board, you can choose whether to rename
only this polygon (and thus move it from one signal into another), or to
give the entire signal a different name.
<a name=69>
<h1>NET</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Draws nets on a schematic.
<dt>
<b>Syntax</b>
<dd>
<tt>NET [net_name] &#149; [curve | @radius] &#149;..</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Right</mb> changes the wire bend style (see <a href=#92>SET Wire_Bend</a>).<br>
<mb>Shift+Right</mb> reverses the direction of switching bend styles.<br>
<mb>Ctrl+Right</mb> toggles between corresponding bend styles.
</dl>
<b>See also</b> <a href=#35>BUS</a>,
<a href=#68>NAME</a>,
<a href=#38>CLASS</a>,
<a href=#92>SET</a>
<p>
The net command is used to draw individual connections (nets) onto
the Net layer of a schematic drawing. The first mouse click marks
the starting point for the net, the second marks the end point of
a segment. Two mouse clicks on the same point end the net.
<p>
If a net wire is placed at a point where there is already another net
or bus wire or a pin, the current net wire will be ended at that point.
This function can be disabled with "<tt>SET AUTO_END_NET OFF;</tt>",
or by unchecking "Options/Set/Misc/Auto end net and bus".
<p>
If a net wire is placed at a point where there are at least two other
net wires and/or pins, a junction will automatically be placed.
This function can be disabled with "<tt>SET AUTO_JUNCTION OFF;</tt>",
or by unchecking "Options/Set/Misc/Auto set junction".
<p>
If the <i>curve</i> or <i>@radius</i> parameter is given, an arc can be drawn as part of the net
(see the detailed description in the <a href=#106>WIRE</a> command).
<h2>Select Bus Signal</h2>
If a net is started on a bus, a popup menu opens from which one of
the bus signals can be selected. The net then is named correspondingly
and becomes part of the same signal. If the bus includes several part
buses, a further popup menu opens from which the relevant part bus
can be selected.
<h2>Net Names</h2>
If the NET command is used with a net name
then the net is named accordingly.
<p>
If no net name is included in the command line and the net is not
started on a bus, then a name in the form of N$1 is automatically
allocated to the net.
<p>
Nets or net segments that run over different sheets of a schematic and use
the same net name are connected.
<p>
Net names should not contain a comma (<tt>','</tt>), because this
is the delimiting character in <a href=#35>busses</a>.
<h2>Line Width</h2>
The width of the line drawn by the net command may be changed with
the command:
<pre>
SET NET_WIRE_WIDTH width;
</pre>
(Default: 6 mil).
<h2>Inverted signals</h2>
The name of an inverted signal ("active low") can be displayed overlined if it
is preceded with an exclamation mark (<tt>'!'</tt>), as in
<pre>
!RESET
</pre>
which would result in
<pre>
_____
RESET
</pre>
You can find further details about this in the description of the <a href=#99>TEXT</a> command.
<a name=70>
<h1>OPEN</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Opens a library for editing.
<dt>
<b>Syntax</b>
<dd>
<tt>OPEN library_name</tt>
</dl>
<b>See also</b> <a href=#39>CLOSE</a>,
<a href=#102>USE</a>,
<a href=#47>EDIT</a>,
<a href=#91>SCRIPT</a>
<p>
The OPEN command is used to open an existing library or create a new
library. Once the library has been opened or created, an existing
or new symbol, device, or package may be edited.
<p>
This command is mainly used in script files.
<a name=71>
<h1>OPTIMIZE</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Joins wire segments together.
<dt>
<b>Syntax</b>
<dd>
<tt>OPTIMIZE;</tt><br>
<tt>OPTIMIZE signal_name ..</tt><br>
<tt>OPTIMIZE &#149;..</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Ctrl+Right</mb> optimizes the group.
</dl>
<b>See also</b> <a href=#92>SET</a>,
<a href=#97>SPLIT</a>,
<a href=#67>MOVE</a>,
<a href=#89>ROUTE</a>
<p>
The OPTIMIZE command joins wire segments which lie
in one straight line. The individual segments must be on the same
layer and have the same width. This command is useful to reduce the
number of objects in a drawing and to facilitate moving a complete
track instead of individual segments.
<p>
If signal names are given, or a signal is selected, the command affects
only the respective signals.
<h2>Automatic Optimization</h2>
This wire optimization takes place automatically after MOVE, SPLIT,
or ROUTE commands unless it is disabled with the command:
<pre>
SET OPTIMIZING OFF;
</pre>
or you have clicked the same spot twice with the SPLIT command.
<p>
The OPTIMIZE command works in any case, no matter if Optimizing
is enabled or disabled.
<a name=72>
<h1>PACKAGE</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Defines a package variant for a device.
<dt>
<b>Syntax</b>
<dd>
<tt>PACKAGE</tt><br>
<tt>PACKAGE pname vname</tt><br>
<tt>PACKAGE pname@lname vname</tt><br>
<tt>PACKAGE name</tt><br>
<tt>PACKAGE -old_name new_name</tt><br>
<tt>PACKAGE -name</tt>
</dl>
<b>See also</b> <a href=#40>CONNECT</a>,
<a href=#98>TECHNOLOGY</a>,
<a href=#78>PREFIX</a>
<p>
This command is used in the device edit mode to define, delete or rename
a package variant.
In the schematic or board editor the PACKAGE command behaves exactly
like "<a href=#36>CHANGE PACKAGE</a>".
<p>
Without parameters a dialog is opened that allows you to select a package
and define this variant's name.
<p>
The parameters <tt>pname vname</tt> assign the package <tt>pname</tt> to
the new variant <tt>vname</tt>.
<p>
The notation <tt>pname@lname vname</tt> fetches the package <tt>pname</tt>
from library <tt>lname</tt> and creates a new package variant.
This can also be done through the library objects'
<a href=#13>context menu</a> or via <i>Drag&amp;Drop</i> from
the Control Panel's tree view.
<p>
The single parameter <tt>name</tt> switches to the given existing package
variant. If no package variants have been defined yet, and a package of the
given name exists, a new package variant named '' (an "empty" name) with the
given package will be created (this is for compatibility with version 3.5).
<p>
If <tt>-old_name new_name</tt> is given, the package variant <tt>old_name</tt>
is renamed to <tt>new_name</tt>.
<p>
The single parameter <tt>-name</tt> deletes the given package variant.
<p>
The name of a package variant will be appended to the device set name to
form the full device name. If the device set name contains the character <tt>'?'</tt>,
that character will be replaced by the package variant name.
Note that the package variant is processed after the technology, so if the device set
name contains neither a <tt>'*'</tt> nor a <tt>'?'</tt> character, the resulting device
name will consist of <i>device_set_name</i><tt>+</tt><i>technology</i><tt>+</tt><i>package_variant</i>.
<p>
Following the PACKAGE command, the CONNECT command is used to define
the correspondence of pins in the schematic device to pads on the
package.
<p>
The maximum number of technologies per device set is 254.
<p>
When the <a href=#34>BOARD</a> command is used in schematic
editing mode to create a new board, each device is represented on a board
layout with the appropriate package as already defined with the
PACKAGE command.
<a name=73>
<h1>PAD</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Adds pads to a package.
<dt>
<b>Syntax</b>
<dd>
<tt>PAD [diameter] [shape] [orientation] [flags] ['name'] &#149;..</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Right</mb> rotates the pad.<br>
<mb>Shift+Right</mb> reverses the direction of rotating.
</dl>
<b>See also</b> <a href=#96>SMD</a>,
<a href=#36>CHANGE</a>,
<a href=#45>DISPLAY</a>,
<a href=#92>SET</a>,
<a href=#68>NAME</a>,
<a href=#104>VIA</a>,
<a href=#133>Design Rules</a>
<p>
The PAD command is used to add pads to a package. When the PAD command
is active, a pad symbol is attached to the cursor and can be moved
around the screen. Pressing the left mouse button places a pad at
the current position.
Entering a number changes the diameter of the pad (in the actual unit).
Pad diameters can be up to 0.51602 inch (13.1 mm).
<p>
The <tt>orientation</tt> (see description in <a href=#29>ADD</a>)
may be any angle in the range <tt>R0</tt>...<tt>R359.9</tt>. The <tt>S</tt>
and <tt>M</tt> flags can't be used here.
<h2>Example</h2>
<pre>
PAD 0.06 &#149;
</pre>
The pad will have a diameter of 0.06 inch, provided the actual unit
is "inch". This diameter remains as a presetting for successive
operations.
<h2>Pad Shapes</h2>
A pad can have one of the following shapes:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Square </td><td width=20><td></td></tr>
<tr><td>Round </td><td width=20><td></td></tr>
<tr><td>Octagon </td><td width=20><td>octagonal</td></tr>
<tr><td>Long </td><td width=20><td>elongated</td></tr>
<tr><td>Offset </td><td width=20><td>elongated with offset</td></tr>
</table>
<p>
These shapes only apply to the outer layers (Top and Bottom).
In inner layers the shape is always "round".
<p>
With elongated pads, the given diameter defines the smaller side of the pad.
The ratio between the two sides of elongated pads is given by the
parameter Shapes/Elongation in the <a href=#133>Design Rules</a>
of the board (default is 100%, which results in a ratio of 2:1).
<p>
The pad shape or diameter can be selected while the PAD command is
active, or it can be changed with the CHANGE command, e.g.:
<pre>
CHANGE SHAPE OCTAGON &#149;
</pre>
The drill size may also be changed using the CHANGE command. The existing
values then remain in use for successive pads.
<p>
Because displaying different pad shapes and drill holes in their real
size slows down the screen refresh, EAGLE lets you change between
real and fast display mode by the use of the SET commands:
<pre>
SET DISPLAY_MODE REAL | NODRILL;
</pre>
Note that the actual shape and diameter of a pad will be determined by the
<a href=#133>Design Rules</a> of the board the part is used in.
<h2>Pad Names</h2>
Pad names are generated by the program automatically
and can be changed with the NAME command. The name can also be defined
in the PAD command. Pad name display can be turned on or off by means
of the commands:
<pre>
SET PAD_NAMES OFF | ON;
</pre>
This change will be visible after the next screen refresh.
<h2>Flags</h2>
The following <i>flags</i> can be used to control the appearance of a pad:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>NOSTOP</tt> </td><td width=20><td>don't generate solder stop mask</td></tr>
<tr><td><tt>NOTHERMALS</tt> </td><td width=20><td>don't generate thermals</td></tr>
<tr><td><tt>FIRST</tt> </td><td width=20><td>this is the "first" pad (which may be drawn with a special shape)</td></tr>
</table>
<p>
By default a pad automatically generates solder stop mask and thermals as necessary.
However, in special cases it may be desirable to have particular pads not do this.
The above <tt>NO...</tt> flags can be used to suppress these features.<br>
If the <a href=#133>Design Rules</a> of a given board specify that the
"first pad" of a package shall be drawn with a particular shape, the pad marked with
the <tt>FIRST</tt> flag will be displayed that way.<br>
A newly started PAD command resets all flags to their defaults. Once a flag is given
in the command line, it applies to all following pads placed within this PAD command
(except for <tt>FIRST</tt>, which applies only to the pad immediately following this
option).
<h2>Single Pads</h2>
Single pads in boards can be used only by defining a package
with one pad. Via-holes can be placed in board but they don't have
an element name and therefore don't show up in the netlist.
<h2>Alter Package</h2>
It is not possible to add or delete pads in packages which
are already used by a device, because this would change the pin/pad
allocation defined with the CONNECT command.
<a name=74>
<h1>PASTE</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Copies the contents of the paste buffer to a drawing.
<dt>
<b>Syntax</b>
<dd>
<tt>PASTE [ orientation ] &#149;</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Center</mb> mirrors the contents of the paste buffer.<br>
<mb>Right</mb> rotates the contents of the paste buffer.<br>
<mb>Shift+Right</mb> reverses the direction of rotating.
</dl>
<b>See also</b> <a href=#42>CUT</a>,
<a href=#54>GROUP</a>
<p>
See the <a href=#29>ADD</a> command for an explanation of Orientation.
<p>
Using the commands GROUP, CUT, and PASTE, parts of a drawing/library
can be copied to the same or different drawings/libraries. When using
the PASTE command, the following points should be observed:
<ul>
<li>CUT/PASTE cannot be used in device editing mode.
<li>Elements and signals on a board can only be copied to a board.
<li>Elements, buses and nets on a schematic can only be copied to a schematic.
<li>Pads and smds can only be copied from package to package.
<li>Pins can only be copied from symbol to symbol.
<li>When copying elements, signals, pads, smds and pins, a new name is
allocated if the previous name is already used in the new drawing.
<li>Buses retain the same names.
<li>Nets retain the same name as long as one of the net segments
has a label. If no label is present, a new name is generated if the previous
name is already in use.
</ul>
If there are modified versions of devices or packages in the paste buffer,
an automatic <a href=#101>library update</a> will be started to replace
the objects in the schematic or board with the ones from the paste buffer.
<b>Note: You should always run a <a href=#46>Design Rule Check</a> (DRC) and an
<a href=#48>Electrical Rule Check</a> (ERC) after a library update has been performed!</b>
<a name=75>
<h1>PIN</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Defines connection points for symbols.
<dt>
<b>Syntax</b>
<dd>
<tt>PIN 'name' options &#149;..</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Right</mb> rotates the pin.<br>
<mb>Shift+Right</mb> reverses the direction of rotating.
</dl>
<b>See also</b> <a href=#68>NAME</a>,
<a href=#93>SHOW</a>,
<a href=#36>CHANGE</a>
<h2>Options</h2>
There are six possible options:
<p>
Direction<br>
Function<br>
Length<br>
Orientation<br>
Visible<br>
Swaplevel
<h3>Direction</h3>
The logical direction of signal flow. It is essential for the Electrical
Rule Check (ERC) and for the automatic wiring of the power supply
pins. The following possibilities may be used:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>NC </td><td width=20><td>not connected</td></tr>
<tr><td>In </td><td width=20><td>input</td></tr>
<tr><td>Out </td><td width=20><td>output (totem-pole)</td></tr>
<tr><td>I/O </td><td width=20><td>in/output (bidirectional)</td></tr>
<tr><td>OC </td><td width=20><td>open collector or open drain</td></tr>
<tr><td>Hiz </td><td width=20><td>high impedance output (e.g. 3-state)</td></tr>
<tr><td>Pas </td><td width=20><td>passive (for resistors, capacitors etc.)</td></tr>
<tr><td>Pwr </td><td width=20><td>power input pin (Vcc, Gnd, Vss, Vdd, etc.)</td></tr>
<tr><td>Sup </td><td width=20><td>general supply pin (e.g. for ground symbol)</td></tr>
</table>
<p>
Default: I/O
<p>
If Pwr pins are used on a symbol and a corresponding Sup pin exists
on the schematic, nets are connected automatically. The Sup pin is
not used for components.
<h3>Function</h3>
The graphic representation of the pin:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>None </td><td width=20><td>no special function</td></tr>
<tr><td>Dot </td><td width=20><td>inverter symbol</td></tr>
<tr><td>Clk </td><td width=20><td>clock symbol</td></tr>
<tr><td>DotClk </td><td width=20><td>inverted clock symbol</td></tr>
</table>
<p>
Default: None
<h3>Length</h3>
Length of the pin symbol:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Point </td><td width=20><td>pin with no connection or name</td></tr>
<tr><td>Short </td><td width=20><td>0.1 inch long connection</td></tr>
<tr><td>Middle </td><td width=20><td>0.2 inch long connection</td></tr>
<tr><td>Long </td><td width=20><td>0.3 inch long connection</td></tr>
</table>
<p>
Default: Long
<h3>Orientation</h3>
The orientation of the pin. When placing pins manually the right mouse
button rotates the pin. The parameter "orientation" is mainly
used in script files:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>R0 </td><td width=20><td>connection point on the right</td></tr>
<tr><td>R90 </td><td width=20><td>connection point above</td></tr>
<tr><td>R180 </td><td width=20><td>connection point on the left</td></tr>
<tr><td>R270 </td><td width=20><td>connection point below</td></tr>
</table>
<p>
Default: R0
<h3>Visible</h3>
This parameter defines if pin and/or pad name are visible in the schematic:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Off </td><td width=20><td>pin and pad name not drawn</td></tr>
<tr><td>Pad </td><td width=20><td>pad name drawn, pin name not drawn</td></tr>
<tr><td>Pin </td><td width=20><td>pin name drawn, pad name not drawn</td></tr>
<tr><td>Both </td><td width=20><td>pin and pad name drawn</td></tr>
</table>
<p>
Default: Both
<h3>Swaplevel</h3>
A number between 0 and 255. Swaplevel = 0 indicates that a pin can
not be swapped with another. The allocation of a number greater than
0 indicates that a pin may be swapped with any other in the same symbol
with the same swaplevel number. For example: The inputs of a NAND
gate could be allocated the same swaplevel number as they are all
identical.
<p>
Default: 0
<h2>Using the PIN Command</h2>
The PIN command is used to define connection points on a symbol for
nets. Pins are drawn onto the Symbols layer while additional information
appears on the Pins layer. Individual pins may be assigned various
options in the command line. The options can be listed in any order
or omitted. In this case the default options are valid.
<p>
If a name is used in the PIN command, it must be enclosed in
apostrophes. Pin names can be changed in the symbol edit mode
using the NAME command.
<h2>Automatic Naming</h2>
Pins may be automatically numbered in the following way. In order
to place the pins D0...D7 on a symbol, the first pin is placed with
the following command:
<pre>
PIN 'D0' *
</pre>
and the location for the other pins defined with a mouse click for each.
<h2>Predefine options with CHANGE</h2>
All options may be predefined with CHANGE commands. The options remain
in use until edited by a new PIN or CHANGE command.
<p>
The SHOW command may be used to show pin options such as Direction
and Swaplevel.
<h2>Pins with the same Name</h2>
If it is required to define several pins in a component with the same
name, the following procedure can be used:
<p>
For example, suppose that three pins are required for
GND. The pins are allocated the names GND@1, GND@2 and GND@3 during
the symbol definition. Then only the characters before the "@"
sign appear in the schematic.
<p>
It is not possible to add or delete pins in symbols
which are already used by a device because this would change the pin/pad
allocation defined with the CONNECT command.
<h2>Pin Lettering</h2>
The position of pin and pad names on a symbol relative
to the pin connection point can not be changed, nor can the text size.
When defining new symbols please ensure their size is consistent with
existing symbols.
<h2>Inverted pins</h2>
The name of an inverted pin ("active low") can be displayed overlined if it
is preceded with an exclamation mark (<tt>'!'</tt>), as in
<pre>
!RESET
</pre>
which would result in
<pre>
_____
RESET
</pre>
You can find further details about this in the description of the <a href=#99>TEXT</a> command.
<a name=76>
<h1>PINSWAP</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Swap pins or pads.
<dt>
<b>Syntax</b>
<dd>
<tt>PINSWAP &#149; &#149;..</tt>
</dl>
<b>See also</b> <a href=#75>PIN</a>
<p>
The PINSWAP command is used to swap pins within the same symbol which
have been allocated the same swaplevel (&gt; 0). Swaplevel, see PIN command.
If a board is tied to a schematic via
<a href=#341>Back Annotation</a>
two pads can only
be swapped if the related pins are swappable.
<p>
On a board without a schematic this command permits two pads in the
same package to be swapped. The Swaplevel is not checked in this case.
<p>
Wires attached to the swapped pins are moved with the pins so that
short circuits may appear. Please perform the DRC and correct possible
errors.
<a name=77>
<h1>POLYGON</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Draws polygon areas.
<dt>
<b>Syntax</b>
<dd>
<tt>POLYGON [signal_name] [width] &#149; [curve | @radius] &#149; &#149;..</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Center</mb> selects the layer.<br>
<mb>Right</mb> changes the wire bend style (see <a href=#92>SET Wire_Bend</a>).<br>
<mb>Shift+Right</mb> reverses the direction of switching bend styles.<br>
<mb>Ctrl+Right</mb> toggles between corresponding bend styles.<br>
<mb>Ctrl+Left</mb> when placing a wire end point defines arc radius.<br>
<mb>Left</mb> twice at the same point closes the polygon.
</dl>
<b>See also</b> <a href=#36>CHANGE</a>,
<a href=#43>DELETE</a>,
<a href=#81>RATSNEST</a>,
<a href=#87>RIPUP</a>,
<a href=#106>WIRE</a>,
<a href=#66>MITER</a>
<p>
The POLYGON command is used to draw polygon areas. Polygons in the
layers Top, Bottom, and Route2..15 are treated as signals. Polygons
in the layers t/b/vRestrict are protected areas for the Autorouter.
<p>
If the <i>curve</i> or <i>@radius</i> parameter is given, an arc can be drawn as part of the polygon
definition (see the detailed description in the <a href=#106>WIRE</a>
command).
<h2>Note</h2>
You should avoid using very small values for the <i>width</i> of a
polygon, because this can cause extremely large amounts of data when
processing a drawing with the <a href=#113>CAM Processor</a>.<br>
The polygon <i>width</i> should always be larger than the hardware
resolution of the output device. For example when using a Gerber photoplotter
with a typical resolution of 1 mil, the polygon <i>width</i> should
not be smaller than, say, 6 mil. Typically you should keep the polygon
<i>width</i> in the same range as your other wires.
<p>
If you want to give the polygon a name that starts with a digit (as in <tt>0V</tt>),
you must enclose the name in single quotes to distinguish it from a <i>width</i> value.
<p>
The parameters <tt>Isolate</tt> and <tt>Rank</tt> only have a meaning for polygons
in layers Top...Bottom.
<h2>Outlines or Real Mode</h2>
Polygons belonging to a signal can be displayed in two different
modes:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>1.&nbsp;Outlines </td><td width=20><td>only the outlines as defined by the user are displayed.</td></tr>
<tr><td>2.&nbsp;Real&nbsp;mode </td><td width=20><td>all of the areas are visible as calculated by the program.</td></tr>
</table>
<p>
In "outlines" mode a polygon is drawn with dotted wires, so that it can be
distinguished from other wires.
The board file contains only the "outlines".
<p>
The default display mode is "outlines" as the calculation is a time
consuming operation.
<p>
When a drawing is generated with the CAM Processor all polygons are
calculated.
<p>
The <a href=#81>RATSNEST</a>
command starts the calculation of the polygons
(this can be turned off with
<tt><a href=#92>SET</a> POLYGON_RATSNEST OFF;</tt>).
Clicking the STOP button terminates the calculation of the polygons. Already
calculated polygons are shown in "real mode", all others are shown in
"outline mode".
<p>
The
<a href=#87>RIPUP</a>
command changes the display mode of a polygon to "outline".
<p>
CHANGE operations re-calculate a polygon if it was shown in "real
mode" before.
<h2>Other commands and Polygons</h2>
Polygons are selected at their edges (like wires).
<p>
SPLIT: Inserts a new polygon edge.
<p>
DELETE: Deletes a polygon corner (if only three corners are left the
whole polygon is deleted).
<p>
CHANGE LAYER: Changes the layer of the whole polygon.
<p>
CHANGE WIDTH: Changes the parameter width of the whole polygon.
<p>
MOVE: Moves a polygon edge or corner (like wire segments).
<p>
COPY: Copies the whole polygon.
<p>
NAME: If the polygon is located in a signal layer the name of the
signal is changed.
<h2>Parameters</h2>
<h3>Width</h3>
Line width of the polygon edges. Also used for filling.
<h3>Layer</h3>
Polygons can be drawn into any layer.
Polygons in signal layers belong to a signal and keep the distance
defined in the design rules and net classes from other signals.
Objects in the tRestrict layer are substracted from polygons in the
Top layer (the same applies to bRestrict/Bottom). This allows you, for
instance, to generate "negative" text on a ground area.
<h3>Pour</h3>
Fill mode (Solid [default] or Hatch).
<h3>Rank</h3>
Defines how polygons are subtracted from each other. Polygons with
a lower 'rank' appear "first" and thus get subtracted from polygons with a higher 'rank'.<br>
Valid ranks are <tt>1..6</tt> for signal polygons and <tt>0</tt> or <tt>7</tt> for
polygons in packages. Polygons with the same rank are checked against each other
by the <a href=#46>Design Rule Check</a>. The rank parameter only has a
meaning for polygons in signal layers (<tt>1..16</tt>) and will be ignored for
polygons in other layers. The default is <tt>1</tt> for signal polygons and <tt>7</tt>
for package polygons.
<h3>Thermals</h3>
Defines how pads and smds are connected (On
= thermals are generated [default], Off = no thermals).
<h3>Spacing</h3>
Distance between fill lines when Pour = Hatch
(default: 50 Mil).
<h3>Isolate</h3>
Distance between polygon areas and other signals or objects in
the Dimension layer (default: 0).
If a particular polygon is given an Isolate value that exceeds that from the
design rules and net classes, the larger value will be taken.
See also <a href=#133>Design Rules</a> under <b>Distance</b> and <b>Supply</b>, respectively.
<h3>Orphans</h3>
As a polygon automatically keeps a certain distance
to other signals it can happen that the polygon is separated into
a number of smaller polygons. If such a polygon has no electrical
connection to any other (non-polygon) object of its signal,
the user might want it to disappear. With the parameter Orphans&nbsp;=&nbsp;Off
[default] these isolated zones will disappear. With Orphans&nbsp;=&nbsp;On they
will remain. If a signal consists only of polygons and has no other electrically
connected objects, all polygon parts will remain, independent of the setting of
the Orphans parameter.
<p>
Under certain circumstances, especially with Orphans&nbsp;=&nbsp;Off,
a polygon can disappear completely.
In that case the polygon's original outlines will be displayed on the
screen, to make it possible to delete or otherwise modify it.
When going to the printer or CAM Processor these outlines will not
be drawn in order to avoid short circuits.
A polygon is also displayed with its original outlines if there are
other non-polygon objects in the signal, but none of them is connected
to the polygon.
<h2>Thermal dimensions</h2>
The width of the conducting path in the thermal symbol is calculated
as follows:
<ul>
<li>Pads: half the drill diameter of the pad
<li>Smds: half the smaller side of the smd
<li>at least the width of the polygon
<li>a maximum of twice the width of the polygon
</ul>
<h2>Outlines data</h2>
The special signal name _OUTLINES_ gives a polygon certain properties that
are used to generate <a href=#130>outlines data</a> (for example
for milling prototype boards).
This name should not be used otherwise.
<h2>Hatched polygons and airwires </h2>
Depending on the value of the <i>spacing</i> parameter, pads, smds, vias and wires inside a
hatched polygon that are connected to the same signal as the polygon may "fall through"
the raster and thus have airwires generated to indicate their connection to the
signal.
<p>
When calculating whether such an object is actually solidly connected to the
hatched polygon, it is reduced to several "control points". For a round pad, for
instance, these would be the north, east, west and south point on the pad's
circumference, while for a wire it's the two end points. A solid connection is
considered to exist if there is at least one line in the calculated polygon (outline
or hatch line) that runs through these points with its center line.
<p>
Thermal and annulus rings inside a hatched polygon that do not have solid contact to
any of the polygon lines are not generated.
<a name=78>
<h1>PREFIX</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Defines the prefix for a symbol name.
<dt>
<b>Syntax</b>
<dd>
<tt>PREFIX prefix_string;</tt>
</dl>
<b>See also</b> <a href=#40>CONNECT</a>,
<a href=#72>PACKAGE</a>,
<a href=#103>VALUE</a>
<p>
This command is used in the device editor mode to determine the initial
characters of automatically generated symbol names when a symbol is
placed in a schematic using the ADD command.
<h2>Example</h2>
<pre>
PREFIX U;
</pre>
If this command is used when editing, for example, a 7400 device, then
gates which are later placed in a schematic using the ADD command
will be allocated the names U1, U2, U3 in sequence. These names may
be changed later with the NAME command.
<a name=79>
<h1>PRINT</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Prints a drawing to the system printer.
<dt>
<b>Syntax</b>
<dd>
<tt>PRINT [factor] [-limit] [options] [;]</tt>
</dl>
<b>See also</b> <a href=#113>CAM Processor</a>,
<a href=#109>printing to the system printer</a>
<p>
The PRINT command prints the currently edited drawing to the system printer.
<p>
Colors and fill styles are used as set in the editor window. This can be
changed with the <tt>SOLID</tt> and <tt>BLACK</tt> options.
The color palette used for the printout is always that for white background.
<p>
If you want to print pads and vias "filled" (without the drill holes
being visible), use the command
<pre>
<a href=#92>SET</a> DISPLAY_MODE NODRILL;
</pre>
<b>Please note that polygons in boards will not be automatically calculated
when printing via the PRINT command! Only the outlines will be drawn.
To print polygons in their calculated shape you have to use the
<a href=#81>RATSNEST</a> command before printing.</b>
<p>
You can enter a <tt>factor</tt> to scale the output.
<p>
The <tt>limit</tt> parameter is the maximum number of pages you want the
output to use. The number has to be preceded with a <tt>'-'</tt> to
distinguish it from the <tt>factor</tt>.
In case the drawing does not fit on the given number of pages, the <tt>factor</tt>
will be reduced until it fits.
Set this parameter to <tt>-0</tt> to allow any number of pages (and thus making sure
the printout uses exactly the given scale factor).
<p>
If the PRINT command is not terminated with a <tt>';'</tt>,
a <a href=#110>print dialog</a> will allow you to set
print options.
Note that options entered via the command line will not be stored permanently in the print setup
unless they have been confirmed in the <a href=#110>print dialog</a>
(i.e. if the command has not been terminated with a <tt>';'</tt>).
<p>
The following <tt>options</tt> exist:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>MIRROR</tt> </td><td width=20><td>mirrors the output</td></tr>
<tr><td><tt>ROTATE</tt> </td><td width=20><td>rotates the output by 90&deg;</td></tr>
<tr><td><tt>UPSIDEDOWN</tt> </td><td width=20><td>rotates the drawing by 180&deg;. Together with <tt>ROTATE</tt>, the drawing is rotated by a total of 270&deg;</td></tr>
<tr><td><tt>BLACK</tt> </td><td width=20><td>ignores the color settings of the layers and prints everything in black</td></tr>
<tr><td><tt>SOLID</tt> </td><td width=20><td>ignores the fill style settings of the layers and prints everything in solid</td></tr>
<tr><td><tt>CAPTION</tt> </td><td width=20><td>prints a caption at the bottom of the page</td></tr>
<tr><td><tt>FILE</tt> </td><td width=20><td>prints the output into a file; the file name must immediately follow this option</td></tr>
<tr><td><tt>PRINTER</tt> </td><td width=20><td>prints to a specific printer; the printer name must immediately follow this option</td></tr>
<tr><td><tt>PAPER</tt> </td><td width=20><td>prints on the given paper size; the paper size must immediately follow this option</td></tr>
<tr><td><tt>SHEETS</tt> </td><td width=20><td>prints the given range of sheets; the range (from-to) must immediately follow this option</td></tr>
<tr><td><tt>WINDOW</tt> </td><td width=20><td>prints the currently visible window selection of the drawing</td></tr>
<tr><td><tt>PORTRAIT</tt> </td><td width=20><td>prints in portrait orientation</td></tr>
<tr><td><tt>LANDSCAPE</tt> </td><td width=20><td>prints in landscape orientation</td></tr>
</table>
<p>
If any of the <tt>options</tt> <tt>MIRROR</tt>...<tt>CAPTION</tt> is preceeded with a <tt>'-'</tt>, that option is turned off in case
it is currently on (from a previous PRINT).
A <tt>'-'</tt> by itself turns off all <tt>options</tt>.
<h2>Printing to a file</h2>
The <tt>FILE</tt> option can be used to print the output into a file.
If this option is present, it must be immediately followed by the name of the output file.
<p>
If the output file name has an extension of <tt>".pdf"</tt> (case insensitive),
a PDF file will be created. A PDF file can also be created by selecting "Print to File (PDF)"
from the "Printer" combo box in the <a href=#110>print dialog</a>.
Texts in a PDF file can be searched in a PDF viewer, as long as they are not
using the vector font.
<p>
If the output file name has an extension of <tt>".ps"</tt> (case insensitive),
a Postscript file will be created.
<p>
If the file name is only an <tt>"*"</tt> or <tt>"*.ext"</tt> (an asterisk followed
by an extension, as in <tt>"*.pdf"</tt>, for instance), a file dialog will be opened
that allows the user to select or enter the actual file name.
<p>
If the file name is only an extension, as in <tt>".pdf"</tt>, the output file name
will be the same as the drawing file name, with the extension changed to the given
string.
<p>
The file name may contain one or more of the following placeholders, which
will be replaced with the respective string:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>%E</tt> </td><td width=20><td>the loaded file's extension (without the <tt>'.'</tt>)</td></tr>
<tr><td><tt>%N</tt> </td><td width=20><td>the loaded file's name (without path and extension)</td></tr>
<tr><td><tt>%P</tt> </td><td width=20><td>the loaded file's directory path (without file name)</td></tr>
<tr><td><tt>%%</tt> </td><td width=20><td>the character <tt>'%'</tt></td></tr>
</table>
<p>
For example, the file name
<p>
<tt>%N.cmp.pdf</tt>
<p>
would create <tt><i>boardname</i>.cmp.pdf</tt>.
<p>
If both the <tt>FILE</tt> and the <tt>PRINTER</tt> option are present, only the last one
given will be taken into account
<h2>Printing to a given paper size</h2>
The <tt>PAPER</tt> option defines the size of the paper to print on.
It must be immediately followed by one of the paper size names listed in
the <i>Paper</i> combo box of the PRINT dialog, like <tt>A4</tt>, <tt>Letter</tt> etc.
If a custom paper size shall be set, it has to be given in the format
<pre>
Width x Height Unit
</pre>
(without blanks), as in
<pre>
PRINT PAPER 200x300mm
PRINT PAPER 8.0x11.5inch
</pre>
<i>Width</i> and <i>Height</i> can be floating point numbers, and the <i>Unit</i>
may be either <tt>mm</tt> or <tt>inch</tt> (the latter may be abbreviated as <tt>in</tt>).
Paper names must be given in full, and are case insensitive.
If both the <tt>PRINTER</tt> and <tt>PAPER</tt> option are used, the <tt>PRINTER</tt>
option must be given first.
Custom paper sizes may not work with all printers. They are mainly for use
with Postscript or PDF output.
<h2>Printing a range of sheets</h2>
The <tt>SHEETS</tt> option can be used to print a range of sheets from a schematic.
The range is given as two numbers, delimited by a <tt>'-'</tt>, as in <tt>2-15</tt>.
Without this option, only the currently edited sheet is printed.
To print all sheets, the range <tt>ALL</tt> can be used (which is case insensitive,
but must be written in full).
A range can also consist of just a single number, as in <tt>42</tt>, which will
print exactly that sheet.
If no schematic is loaded, this option has no meaning.
<h2>Examples</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>PRINT</tt> </td><td width=20><td>opens the <a href=#110>print dialog</a> in which you can set print options</td></tr>
<tr><td><tt>PRINT;</tt> </td><td width=20><td>immediately prints the drawing with the default options</td></tr>
<tr><td><tt>PRINT - MIRROR BLACK SOLID;</tt> </td><td width=20><td>prints the drawing mirrored, with everything in black and solid</td></tr>
<tr><td><tt>PRINT 2.5 -1;</tt> </td><td width=20><td>prints the drawing enlarged by a factor of 2.5, but makes sure that it does not exceed <b>one</b> page</td></tr>
<tr><td><tt>PRINT FILE .pdf;</tt> </td><td width=20><td>prints the drawing into a PDF file with the same name as the drawing file</td></tr>
<tr><td><tt>PRINT SHEETS 2-15 FILE .pdf;</tt> </td><td width=20><td>prints the sheets 2 through 15 into a PDF file with the same name as the drawing file</td></tr>
</table>
<a name=80>
<h1>QUIT</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Quits the program
<dt>
<b>Syntax</b>
<dd>
<tt>QUIT</tt>
</dl>
This command ends the editing session. If any changes have been made
but the drawing has not yet been saved, a popup menu will ask you
if you want to save the drawing/library first.
<p>
You can also exit from EAGLE at any time by pressing <tt>Alt+X</tt>.
<a name=81>
<h1>RATSNEST</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Calculates the shortest possible airwires and polygons.
<dt>
<b>Syntax</b>
<dd>
<tt>RATSNEST</tt><br>
<tt>RATSNEST signal_name ..</tt><br>
<tt>RATSNEST ! signal_name ..</tt>
</dl>
<b>See also</b> <a href=#94>SIGNAL</a>,
<a href=#67>MOVE</a>,
<a href=#77>POLYGON</a>,
<a href=#87>RIPUP</a>
<p>
The RATSNEST command assesses the airwire connections in order
to achieve the shortest possible paths, for instance, after components
have been moved. After reading a netlist via the
<a href=#91>SCRIPT</a>
command, it is also useful to use the RATSNEST command to optimize the
length of airwires.
<p>
The RATSNEST command also calculates all polygons belonging to a
signal. This is necessary in order to avoid the calculation of
airwires for pads already connected through polygons. All of the calculated
polygon areas are then being displayed in the "real mode".
You can switch back to the faster
"outline mode" with the RIPUP command.<br>
The automatic calculation of the polygons can be turned off with
<pre>
<a href=#92>SET</a> POLYGON_RATSNEST OFF;
</pre>
RATSNEST ignores airwires representing signals which have
their own layer in a multilayer board (e.g. layer $GND for signal
GND), apart from signals connecting smd pads to a supply layer with
a via-hole.
<p>
Note that RATSNEST doesn't mark the board drawing as modified, since the
calculated polygon data (if any) is not stored in the board, and the
recalculated airwires don't really constitute a modification of the drawing.
<h2>Zero length airwires</h2>
If two or more wires of the same signal on different routing layers end
at the same point without being connected through a pad or a via, a
<i>zero length airwire</i> is generated, which will be displayed
as an X-shaped cross in the Unrouted layer. The same applies to smds that
belong to the same signal and are placed on opposite sides of the board.
<p>
Such <i>zero length airwires</i> can be picked up with the
<a href=#89>ROUTE</a> command just like ordinary airwires.
They may also be handled by placing a <a href=#104>VIA</a>
at that point.
<h2>Making sure everything has been routed</h2>
If there is nothing left to be routed, the RATSNEST command will respond
with the message
<pre>
Ratsnest: Nothing to do!
</pre>
Otherwise, if there are still airwires that have not been routed, the
message
<pre>
Ratsnest: xx airwires.
</pre>
will be displayed, where <tt>xx</tt> gives the number of unrouted airwires.
<h2>Wildcards</h2>
If a <tt>signal_name</tt> parameter is given, the characters <tt>'*'</tt>, <tt>'?'</tt>
and <tt>'[]'</tt> are <i>wildcards</i> and have the following meaning:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>*</tt> </td><td width=20><td>matches any number of any characters</td></tr>
<tr><td><tt>?</tt> </td><td width=20><td>matches exactly one character</td></tr>
<tr><td><tt>[...]</tt></td><td width=20><td>matches any of the characters between the brackets</td></tr>
</table>
<p>
If any of these characters shall be matched exactly as such, it has to be enclosed
in brackets. For example, <tt>abc[*]ghi</tt> would match <tt>abc*ghi</tt> and not
<tt>abcdefghi</tt>.
<p>
A range of characters can be given as <tt>[a-z]</tt>, which results in any character
in the range <tt>'a'</tt>...<tt>'z'</tt>.
<h2>Hiding selected airwires</h2>
Sometimes it may be useful to hide the airwires of selected signals, for instance
if these will later be connected through a polygon. Typically this could be supply
signals, which have a lot of airwires that will never be routed explicitly and
just obscure the other signals' airwires.
<p>
To hide airwires the RATSNEST command can be given the exclamation mark (<tt>'!'</tt>),
followed by a list of signals, as in
<pre>
RATSNEST ! GND VCC
</pre>
which would hide the airwires of the signals <tt>GND</tt> and <tt>VCC</tt>.<br>
To have the airwires displayed again just enter the RATSNEST command without the
<tt>'!'</tt> character, and the list of signals:
<pre>
RATSNEST GND VCC
</pre>
This will activate the display of the airwires of the signals <tt>GND</tt> and <tt>VCC</tt>
and also recalculates them. You can also recalculate the airwires (and polygons) of
particular signals this way.
<p>
The signal names may contain wildcards, and the two variants may be combined, as in
<pre>
RATSNEST D* ! ?GND VCC
</pre>
which would recalculate and display the airwires of all signals with names beginning
with <tt>'D'</tt>, and hide the airwires of all the various GND signals (like AGND, DGND etc.)
and the VCC signal. Note that the command is processed from left to right, so in case
there is a DGND signal the example would first process it for display, but then
hide its airwires.
<p>
To make sure all airwires are displayed enter
<pre>
RATSNEST *
</pre>
Note that the <a href=#94>SIGNAL</a> command will automatically
make the airwires of a signal visible if a new airwire is created for that signal.
The <a href=#87>RIPUP</a> command on the other hand will not change
the state of hiding airwires if a wire of a signal is changed into an airwire.
<a name=82>
<h1>RECT</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Adds rectangles to a drawing.
<dt>
<b>Syntax</b>
<dd>
<tt>RECT [orientation] &#149; &#149;..</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Center</mb> selects the layer.
</dl>
<b>See also</b> <a href=#37>CIRCLE</a>
<p>
The RECT command is used to add rectangles to a drawing. The two points
define two opposite corners of the rectangle. Pressing the center
mouse button changes the layer to which the rectangle is to be added.
<p>
The <tt>orientation</tt> (see description in <a href=#29>ADD</a>)
may be any angle in the range <tt>R0</tt>...<tt>R359.9</tt>. The <tt>S</tt>
and <tt>M</tt> flags can't be used here.
Note that the coordinates are always defined at an orientation of <tt>R0</tt>.
The possibility of entering an <tt>orientation</tt> in the RECT command is
mainly for use in scripts, where the rectangle data may have been derived
through a User Language Program from the <a href=#200>UL_RECTANGLE</a>
object. When entering a non-zero orientation interactively, the corners of
the rectangle may not appear at the actual cursor position.
Use the <a href=#88>ROTATE</a> command to interactively rotate
a rectangle.
<h2>Not Part of Signals</h2>
Rectangles in the signal layers Top, Bottom, or Route2...15 don't
belong to signals. Therefore the DRC reports errors if they overlap
with wires, pads etc.
<h2>Restricted Areas</h2>
If used in the layers tRestrict, bRestrict, or vRestrict, the RECT
command defines restricted areas for the Autorouter.
<a name=83>
<h1>REDO</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Executes a command that was reversed by UNDO.
<dt>
<b>Syntax</b>
<dd>
<tt>REDO;</tt>
<dt>
<b>Keyboard</b>
<dd>
<tt>F10: REDO</tt> execute the REDO command.<br>
<tt>Shift+Alt+BS: REDO</tt>
</dl>
<b>See also</b> <a href=#100>UNDO</a>,
<a href=#341>Forward&amp;Back Annotation</a>
<p>
In EAGLE it is possible to reverse previous actions with the UNDO
command. These actions can be executed again by the REDO command.
UNDO and REDO operate with a command memory which exists back to the
last EDIT, OPEN, AUTO or REMOVE command.
<p>
UNDO/REDO is completely integrated within Forward&amp;Back Annotation.
<a name=84>
<h1>REMOVE</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Deletes files, devices, symbols, packages, and sheets.
<dt>
<b>Syntax</b>
<dd>
<tt>REMOVE name</tt><br>
<tt>REMOVE name.Sxx</tt>
</dl>
<b>See also</b> <a href=#70>OPEN</a>,
<a href=#85>RENAME</a>
<h2>Files</h2>
The REMOVE command is used to delete the file <tt>name</tt> if in
board or schematic editing mode.
<h2>Devices, Symbols, Packages</h2>
The REMOVE command is used to delete the device, symbol or package
"name" from the presently opened library.
The name may include an extension (for example REMOVE name.pac). If the name is given without
extension, you have to be in the respective mode to remove an object
(i.e. editing a package if you want to remove packages).
<p>
Symbols and packages can be erased from a library only
if not used by a device.
<h2>Sheets</h2>
The REMOVE command may also be used to delete a sheet from a schematic.
The name of the presently loaded schematic can be omitted.
The parameter xx represents the sheet number, for example:
<pre>
REMOVE .S3
</pre>
deletes sheet number 3 from the presently loaded schematic.
<p>
If you delete the currently loaded sheet, sheet number 1 will be loaded
after the command has been executed. All sheets with a higher number
than the one deleted will get a number reduced by one.
<p>
UNDO does not work with this command. If you have deleted a sheet
accidentally it will be present in the "old" schematic file
as long as the "new" file has not been saved.
<p>
REMOVE clears the UNDO buffer.
<a name=85>
<h1>RENAME</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Renames symbols, devices or packages.
<dt>
<b>Syntax</b>
<dd>
<tt>RENAME old_name new_name;</tt>
</dl>
<b>See also</b> <a href=#70>OPEN</a>
<p>
The RENAME command is used to change the name of a symbol, device
or package. The appropriate library must have been opened by the OPEN
command before.
<p>
The names may include extensions (for example RENAME name1.pac name2[.pac] - note that the
extension is optional in the second parameter). If the first parameter
is given without extension, you have to be in the respective mode to
rename an object (i.e. editing a package if you want to rename packages).
<p>
RENAME clears the UNDO buffer.
<a name=86>
<h1>REPLACE</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Replace a part.
<dt>
<b>Syntax</b>
<dd>
<tt>REPLACE &#149;..</tt><br>
<tt>REPLACE device_name &#149;..</tt><br>
<tt>REPLACE part_name device_name ..</tt><br>
<tt>REPLACE package_name &#149;..</tt><br>
<tt>REPLACE element_name package_name ..</tt>
</dl>
<b>See also</b> <a href=#92>SET</a>,
<a href=#101>UPDATE</a>
<p>
The REPLACE command can be used to replace a part with a different
device (even from a different library). The old and new device must
be compatible, which means that their used gates and connected pins/pads must
match, either by their names or their coordinates.
<p>
Without parameters the REPLACE command opens a dialog from which a device
can be selected from all libraries that are currently in <a href=#102>use</a>.
After such a device has been selected, subsequent mouse clicks on parts
will replace those parts' devices with the selected one if possible.
<p>
If a <tt>device_name</tt> is given, that device will be used for the replace
operation.
<p>
With both a <tt>part_name</tt> and a <tt>device_name</tt>, the device of
the given part will be replaced (this is useful when working with scripts).
<p>
If only a board is being edited (without a schematic), or if elements in the
board are being replaced that have no matching part in the schematic,
the REPLACE command has two different modes that are chosen by the
SET command.
<p>
The first mode (default) is activated by the command:
<pre>
SET REPLACE_SAME NAMES;
</pre>
In this mode the new package must have the same pad and smd names
as the old one. It may be taken from a different library and it may
contain additional pads and smds. The position of pads
and smds is irrelevant.
<p>
The second mode is activated by the command
<pre>
SET REPLACE_SAME COORDS;
</pre>
In this mode, pads and smds of the new package must
be placed at the same coordinates as in the old one (relative to the
origin). Pad and smd names may be different. The new package may be
taken from a different library and may contain additional pads and
smds.
<p>
Pads of the old package connected with signals must be present in the
new package. If this condition is true the new package may have less
pads than the old one.
<p>
REPLACE functions only when the appropriate tOrigins/bOrigins
layer is displayed.
<p>
If there is already a package with the same name (from the same library) in the drawing,
and the library has been modified after the original object was added, an automatic
<a href=#101>library update</a> will be started and you will be asked whether
objects in the drawing shall be replaced with their new versions.
<p>
<b>Note: A REPLACE operation automatically updates all involved library objects
as necessary. This means that other parts (on other schematic sheets or in
other locations on the board) may be changed, too.
You should always run a <a href=#46>Design Rule Check</a> (DRC) and an
<a href=#48>Electrical Rule Check</a> (ERC) after a REPLACE operation!</b>
<a name=87>
<h1>RIPUP</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Changes routed wires and vias into airwires.<br>
Changes the display of polygons to "outlines".
<dt>
<b>Syntax</b>
<dd>
<tt>RIPUP;</tt><br>
<tt>RIPUP [ @ ] [ ! ] &#149;..</tt><br>
<tt>RIPUP [ @ ] [ ! ] signal_name..</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Ctrl+Right</mb> rips up the group.
</dl>
<b>See also</b> <a href=#43>DELETE</a>,
<a href=#54>GROUP</a>,
<a href=#77>POLYGON</a>,
<a href=#81>RATSNEST</a>
<p>
The RIPUP command changes routed wires (tracks) into airwires. That
can be done for:
<ul>
<li>all signals (RIPUP;)
<li>all signals except certain ones (e.g. RIPUP ! GND VCC;)
<li>one or more signals (e.g. RIPUP D0 D1 D2;)
<li>certain segments (chosen with one or more mouse clicks)
<li>all polygons (RIPUP @;)
<li>all polygons of certain signals (e.g. RIPUP @ GND VCC;)
<li>all polygons except those of certain signals (e.g. RIPUP @ ! GND VCC;)
</ul>
Selecting an airwire with RIPUP converts all adjacent routed wires and vias
into airwires, up to the next pad, smd or airwire.
<pre>
RIPUP signal_name..
</pre>
rips up the complete signal "signal_name" (several signals may be
listed, e.g. <tt>RIPUP D0 D1 D2;</tt>).
<pre>
RIPUP &#149;..
</pre>
rips up segments selected by the mouse click up to the next pad/smd.
<pre>
RIPUP;
</pre>
removes only signals which are connected to elements
(e.g. board crop marks are not affected). The same applies if RIPUP
is used on a group.
<p>
<b>Note:</b> in all cases the RIPUP command only acts on objects that
are in layers that are currently visible!
<h2>Wildcards</h2>
If a <tt>signal_name</tt> parameter is given, the characters <tt>'*'</tt>, <tt>'?'</tt>
and <tt>'[]'</tt> are <i>wildcards</i> and have the following meaning:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>*</tt> </td><td width=20><td>matches any number of any characters</td></tr>
<tr><td><tt>?</tt> </td><td width=20><td>matches exactly one character</td></tr>
<tr><td><tt>[...]</tt></td><td width=20><td>matches any of the characters between the brackets</td></tr>
</table>
<p>
If any of these characters shall be matched exactly as such, it has to be enclosed
in brackets. For example, <tt>abc[*]ghi</tt> would match <tt>abc*ghi</tt> and not
<tt>abcdefghi</tt>.
<p>
A range of characters can be given as <tt>[a-z]</tt>, which results in any character
in the range <tt>'a'</tt>...<tt>'z'</tt>.
<h2>Polygons</h2>
If the RIPUP command with a name is applied to a signal which contains a polygon
the polygon will be displayed with its outlines (faster screen
redraw!). Use the <a href=#81>RATSNEST</a> command to have polygons
displayed in the "real mode" again.
<a name=88>
<h1>ROTATE</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Rotates objects.
<dt>
<b>Syntax</b>
<dd>
<tt>ROTATE orientation &#149;..</tt><br>
<tt>ROTATE orientation name..</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Ctrl+Right</mb> rotates the group.<br>
<mb>Left&amp;Drag</mb> rotates the object by any angle.<br>
<mb>Ctrl+Right&amp;Drag</mb> rotates the group by any angle.
</dl>
<b>See also</b> <a href=#29>ADD</a>,
<a href=#65>MIRROR</a>,
<a href=#67>MOVE</a>,
<a href=#62>LOCK</a>,
<a href=#54>GROUP</a>
<p>
The ROTATE command is used to change the orientation of objects.
<p>
If <tt>orientation</tt> (see description in <a href=#29>ADD</a>) is given,
that value will be added to the orientation of the selected object instead.
<p>
Prepending <tt>orientation</tt> with the character <tt>'='</tt> causes the value
not to be added, but instead to be set absolutely.
<p>
Parts, pads, smds and pins can also be selected by their name,
which is especially useful if the object is outside the currently shown
window area.
For example
<p>
<pre>
ROTATE =MR90 IC1
</pre>
<p>
would set the orientation of element IC1 to MR90, regardless of its previous setting.
<p>
Attributes of parts can be selected by entering the concatenation of
part name and attribute name, as in <tt>R5&gt;VALUE</tt>.
<p>
If <tt>element_name</tt> could be mistaken as an orientation parameter
you need to quote that name, as in
<p>
<pre>
ROTATE R45 'R1'
</pre>
<p>
You can use Click&amp;Drag to rotate an object by any angle.
Just click on the object and move the mouse (with the mouse
button held down) away from the object. After having moved the mouse a
short distance, the object will start rotating. Move the mouse until the
desired angle has been reached and then release the mouse button. If, at
some point, you decide to rather not rotate the object, you can press the
ESCape key while still holding the mouse button pressed.
The same operation can be applied to a group by using the right mouse button.
The group will be rotated around the point where the right mouse button has
been pressed down.
<p>
Parts cannot be rotated if they are <a href=#62>locked</a>,
or if any of their connected pads would extend outside the allowed area
(in case you are using a <a href=#347>limited edition</a> of EAGLE).
<h2>Elements</h2>
When rotating an element, wires (tracks) connected to the element are
moved at the connection points (beware of short circuits!).
<p>
Elements can only be rotated if the appropriate tOrigins/bOrigins
layer is visible.
<h2>Text</h2>
Text is always displayed so that it can be read from the bottom
or from the right - even when rotated. Therefore after every
two rotations it appears the same way, but the origin has moved from
the lower left to the upper right corner. Remember this if a text
appears to be unselectable!
<p>
If you want to have text that is printed "upside down", you can set the "Spin"
flag for that text.
<a name=89>
<h1>ROUTE</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Converts unrouted connections into routed wires (tracks).
<dt>
<b>Syntax</b>
<dd>
<tt>ROUTE [width] &#149; [curve | @radius] &#149;..</tt><br>
<tt>ROUTE name ..</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Ctrl+Left</mb> starts routing at any given point along a wire or via.<br>
<mb>Shift+Left</mb> starts routing with the same width as an existing wire.<br>
<mb>Center</mb> selects the layer.<br>
<mb>Right</mb> changes the wire bend style (see <a href=#92>SET Wire_Bend</a>).<br>
<mb>Shift+Right</mb> reverses the direction of switching bend styles.<br>
<mb>Ctrl+Right</mb> toggles between corresponding bend styles.<br>
<mb>Shift+Left</mb> places a via at the end point.<br>
<mb>Ctrl+Left</mb> when placing a wire end point defines arc radius.
</dl>
<b>See also</b> <a href=#33>AUTO</a>,
<a href=#100>UNDO</a>,
<a href=#106>WIRE</a>,
<a href=#66>MITER</a>,
<a href=#94>SIGNAL</a>,
<a href=#92>SET</a>,
<a href=#81>RATSNEST</a>
<p>
The ROUTE command activates the manual router which allows you to
convert airwires (unrouted connections) into real wires.
<p>
The first point selects an unrouted connection (a wire
in the Unrouted layer) and replaces one end of it by a wire (track).
The end which is closer to the mouse cursor will be taken. Now the
wire can be moved around (see also <a href=#106>WIRE</a>).
The right mouse button will change the wire bend and the center mouse
button will change the layer.
Please note that only those signal layers (1 through 16) are available
that have been entered into the layer setup in the <a href=#133>Design Rules</a>.
<p>
When the final position of the wire
is reached, a further click of the left mouse button will place the
wire and a new wire segment will be attached to the cursor.
If the <tt>Shift</tt> key is held down in such a situation, a Via will
be generated at that point if this is possible and the airwire hasn't already
been completely routed. The generated Via will have either the appropriate
length or, if such a length can't be determined, will go from layer 1 through 16.
<p>
When the layer has been changed and a via-hole is thus necessary,
it will be added automatically as the wire is placed. When the complete
connection has been routed a 'beep' will be given and the next unrouted
connection can be selected for routing.
<p>
Only the minimum necessary vias will be set (according to the layer setup in the
<a href=#133>Design Rules</a>). It may happen that an already existing via of the same signal is
extended accordingly, or that existing vias are combined to form a longer via if
that's necessary to allow the desired layer change.
If a via is placed at the start or end point, and there is an SMD pad
at that location, the via will be a <i>micro via</i> if the current routing
layer is one layer away from the SMD's layer (this applies only if micro vias
have been enabled in the <a href=#133>Design Rules</a>).
<p>
While the ROUTE command is active the wire width can be entered
from the keyboard.
<p>
If the <i>curve</i> or <i>@radius</i> parameter is given, an arc can be drawn as part of the track
(see the detailed description in the <a href=#106>WIRE</a> command).
<p>
If the <tt>Ctrl</tt> key is pressed while selecting the starting point and there
is no airwire at that point, a new airwire will be created automatically. The starting
point of that airwire will be that point on the selected wire or via that is closest to
the mouse cursor (possibly snapped to the nearest grid point). The far end of the
airwire will dynamically point to a target segment that is different from the
selected one. If the selected signal is already completely routed, the far end will
point to the starting point instead.
If the selected wire is an arc, the airwire will start at the closest end point
of the wire.
<p>
If a <tt>name</tt> is given, the airwire of that signal that is closest
to the mouse cursor is selected. If <tt>name</tt> could be interpreted
as a <i>with</i>, <i>curve</i> or <i>@radius</i> it has to be written
in single quotes.
<h2>Selecting the routing layer and wire width</h2>
When you select an airwire, the initial layer in which to route is
determined by considering the objects at the starting point as follows:
<ul>
<li>if there is an object in the current layer, the current layer is kept
<li>else one of the layers of the objects at that point will be taken
</ul>
When selecting an airwire, the wire width for routing
will be that defined by the Design Rules and the net class of the selected signal
if the flag "Options/Set/Misc/Auto set route width and drill" is set.
You can select a different width wile the airwire is attached to the cursor, and
the track will be rerouted with the new width. The same applies to the via data.
<p>
When routing an airwire that starts at an already routed wire, the new
wire's width is automatically adjusted to that of the existing wire
if the <tt>Shift</tt> key is pressed when selecting the airwire.
<h2>Snap Function</h2>
The end point of the dynamically calculated airwire is always used as an
additional snap point, even if it is off grid. If the remaining airwire has
a length that is shorter than SNAP_LENGTH, the routed wire automatically
snaps to the airwire's end point, and stays there until the mouse pointer
is moved at least SNAP_LENGTH away from that point.
The minimum distance for this snap function can be defined with the command
<pre>
SET SNAP_LENGTH distance;
</pre>
where "distance" is the snap radius in the current grid unit.
<h2>Follow-me Router</h2>
With the special <a href=#92>wire bend styles</a> <tt>8</tt> and <tt>9</tt>,
the ROUTE command works as a "Follow-me" router. This means that the selected airwire
will be routed fully automatically by the <a href=#131>Autorouter</a>.
<p>
Wire bend style <tt>8</tt> routes only the shorter side of the selected airwire,
while <tt>9</tt> routes both sides. Once the automatic routing process is complete
(which may take a while, so be patient), the airwire will be replaced by the
actual routed wires and vias. If the routing couldn't be completed (for instance
due to Design Rules restrictions), the cursor changes into a "forbidden" sign.
With bend style <tt>9</tt> it is possible that only one side of the airwire can
be routed, while the other side can't.
<p>
Whenever the mouse is moved, any previous result is discarded and a new calculation
is started. Once the result is acceptable, just click the left mouse button to
place it.
<p>
The Follow-me router works by marking the grid point at the current mouse position
as a starting point, and uses the Autorouter to find a path from that point to any
point along the signal segment at which the selected airwire ends (which is not
necessarily the exact end point of the airwire). The starting point also considers
the currently selected layer, so don't be surprised if the router places a via
at that point. By changing the current layer you can influence the routing result.
<p>
The routing grid is taken from the actual grid setting at the time the airwire
is selected.
<p>
The routing parameters (like cost factors, preferred directions etc.) are those defined
in the dialog of the <a href=#33>AUTO</a> command.
<p>
The following particularities apply:
<ul>
<li>The Follow-me router doesn't calculate the polygons. If you want them to be
calculated, run the <a href=#81>RATSNEST</a> command first.
<li>Since the starting point has to be part of the routed track, the result may
be a T-shaped connection, with an unnecessary wire reaching to the starting
point. Simply move the mouse cursor towards the actual connection to avoid this.
<li>Both ends of the airwire are routed separately in bend style <tt>9</tt>, which
may lead to wires and/or vias overlapping each other. Move the mouse cursor
until such unwanted effects go away.
<li>Depending on the selected routing layer for the start point it may happen that
unnecessary vias are created. Select a different routing layer to avoid this.
<li>If the maximum number of allowed vias is set to <tt>0</tt> in the Follow-me
router parameters, and you change the layer while an airwire is attached to
the mouse cursor, the router may place a via at the starting point of the
short end of the selected airwire (if this is at all possible according to
the Design Rules, restricted areas etc.).
<li>When in Follow-me mode, the right mouse button toggles between routing only the
shorter end of the selected airwire, or both ends. To get back to manual routing
you need to click on one of the bend style buttons, or enter the
<a href=#92>SET Wire_Bend</a> command with a value smaller than <tt>8</tt>.
<li>The Follow-me router can only place round or octagonal shaped Vias, not square ones.
<li>The Miter parameter has no meaning in Follow-me mode.
<li>The parameters for the Follow-me router are stored together with the rest of
the Autorouter parameters, but in a separate section. This is because basically
the Follow-me parameters should behave like those of the "Route" section in the
Autorouter parameters (in order to not obscure too much area), but also might
have a tendency towards those of the optimize sections.
<li>If a board file containing Autorouter parameters is saved with this version of
EAGLE and loaded into an older version, the Autorouter parameters may be
reported as invalid by the older version, and it will use default values.
You can save the Autorouter parameters into a *.ctl file and explicitly load
them into the older version if necessary.
<li>The special mouse key functions
<mb>Ctrl+Left</mb> (start routing at any given point along a wire or via),
<mb>Shift+Left</mb> (place a via at the end point) and
<mb>Ctrl+Left</mb> (define arc radius) don't work in Follow-me mode.
</ul>
<a name=90>
<h1>RUN</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Executes a <a href=#138>User Language</a> Program.
<dt>
<b>Syntax</b>
<dd>
<tt>RUN file_name [argument ...]</tt>
</dl>
<b>See also</b> <a href=#91>SCRIPT</a>
<p>
The RUN command starts the User Language Program from the file <tt>file_name</tt>.<br>
The optional <tt>argument</tt> list is available to the ULP through the
<a href=#242>Builtin Variables</a> <tt>argc</tt> and <tt>argv</tt>.
<h2>Running a ULP from a script file</h2>
If a ULP is executed from a script file and the program returns an integer value
other than <tt>0</tt> (either because it has been terminated through a
call to the <tt><a href=#260>exit()</a></tt> function or because
the STOP button was clicked), execution of the script file will be terminated.
<h2>Editor commands resulting from running a ULP</h2>
A ULP can also use the <tt><a href=#260>exit()</a></tt> function with a <tt>string</tt>
parameter to send a command string back to the editor window.
<a name=91>
<h1>SCRIPT</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Executes a command file.
<dt>
<b>Syntax</b>
<dd>
<tt>SCRIPT file_name;</tt>
</dl>
<b>See also</b> <a href=#92>SET</a>,
<a href=#64>MENU</a>,
<a href=#31>ASSIGN</a>,
<a href=#50>EXPORT</a>,
<a href=#90>RUN</a>
<p>
The SCRIPT command is used to execute sequences of commands that are
stored in a script file. If SCRIPT is typed in at the keyboard and "file_name"
has no extension, the program automatically uses ".scr".
<h2>Examples</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>SCRIPT nofill</tt> </td><td width=20><td>executes nofill.scr</td></tr>
<tr><td><tt>SCRIPT myscr.</tt> </td><td width=20><td>executes myscr (no Suffix)</td></tr>
<tr><td><tt>SCRIPT myscr.old</tt> </td><td width=20><td>executes myscr.old</td></tr>
</table>
<p>
Please refer to the EXPORT command for different possibilities
of script files.
<p>
If the SCRIPT command is selected with the mouse, a popup menu will
show all of the files which have the extension ".scr" so that
they can be selected and executed.
<p>
The SCRIPT command provides the ability to customize
the program according to your own wishes. For instance:
<ul>
<li>change the command menu
<li>assign keys
<li>load pc board shapes
<li>change colors
</ul>
SCRIPT files contain EAGLE commands according to the syntax rules.
Lines beginning with <tt>'#'</tt> are comment.
<h2>Continued Lines</h2>
SCRIPT files contain one or more commands in every line according
to the syntax rules. The character '\' at the end of a command line ensures
that the first word of the next line is not interpreted as a command.
This feature allows you to avoid apostrophes in many cases.
<h2>Set Default Parameters</h2>
The SCRIPT file eagle.scr - if it exists in the project
directory or in the <a href=#14>script path</a> - is executed each time
a new drawing is loaded into an editor window (or when the drawing type is changed
in a library).
<h2>Execute Script Files in the Library Editor</h2>
All of the layers are recognized only if the library editor has previously been loaded.
<a name=92>
<h1>SET</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Alters system parameters
<dt>
<b>Syntax</b>
<dd>
<tt>SET</tt><br>
<tt>SET options;</tt>
</dl>
Parameters which affect the behavior of the program, the screen display, or the user interface can be specified with the SET command. The precise syntax is described below.
<p>
A dialog in which all the parameters can be set appears if the SET command is entered without parameters.
<h2>User Interface</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Snap function </td><td width=20><td><tt>SET SNAP_LENGTH number;</tt></td></tr>
<tr><td> </td><td width=20><td>This sets the limiting value for the snap function in the <a href=#89>ROUTE</a> command (using the current unit).</td></tr>
<tr><td> </td><td width=20><td>Default: 20 mil</td></tr>
<tr><td> </td><td width=20><td>If tracks are being laid with the <a href=#89>ROUTE</a> command to pads that are not on the grid, the snap function will ensure that a route will be laid to the pad within the snap-length.</td></tr>
<tr><td> </td><td width=20><td><tt>SET CATCH_FACTOR value;</tt></td></tr>
<tr><td> </td><td width=20><td>Defines the distance from the cursor up to which objects are taken into account when clicking with the mouse. The value is entered relative to the height (or width, whichever is smaller) of the presently visible part of the drawing. It applies to a zoom level that displays at least a range of 4 inch and inrceases logarithmically when zooming further in. A value of 0 turns this limitation off.<br>Default: 0.05 (5%).</td></tr>
<tr><td> </td><td width=20><td><tt>SET SELECT_FACTOR value;</tt></td></tr>
<tr><td> </td><td width=20><td>This setting controls the distance from the cursor within which nearby objects will be suggested for <a href=#20>selection</a>. The value is entered relative to the height (or width, whichever is smaller) of the presently visible part of the drawing.<br>Default: 0.02 (2%).</td></tr>
<tr><td>Menu contents </td><td width=20><td><tt>SET USED_LAYERS name | number;</tt></td></tr>
<tr><td> </td><td width=20><td>Specifies the layers which will be shown in the associated EAGLE menus. See the example file <tt>mylayers.scr</tt>.</td></tr>
<tr><td> </td><td width=20><td>The layers Pads, Vias, Unrouted, Dimension, Drills and Holes will in any case remain in the menu, as will the schematic layers. Any used signal layers also remain in the menus. <tt>SET Used_Layers All</tt> activates all layers.</td></tr>
<tr><td> </td><td width=20><td><tt>SET WIDTH_MENU value..;</tt></td></tr>
<tr><td> </td><td width=20><td><tt>SET DIAMETER_MENU value..;</tt></td></tr>
<tr><td> </td><td width=20><td><tt>SET DRILL_MENU value..;</tt></td></tr>
<tr><td> </td><td width=20><td><tt>SET SMD_MENU value..;</tt></td></tr>
<tr><td> </td><td width=20><td><tt>SET SIZE_MENU value..;</tt></td></tr>
<tr><td> </td><td width=20><td><tt>SET ISOLATE_MENU value..;</tt></td></tr>
<tr><td> </td><td width=20><td><tt>SET SPACING_MENU value..;</tt></td></tr>
<tr><td> </td><td width=20><td><tt>SET MITER_MENU value..;</tt></td></tr>
<tr><td> </td><td width=20><td>The content of the associated popup menus can be configured with the above command for the parameters <i>width</i> etc.. A maximum of 16 values is possible for each menu (16 value-pairs in the SMD menu). Without any values (as in <tt>SET WIDTH_MENU;</tt>) the program default values will be restored.</td></tr>
<tr><td> </td><td width=20><td>Example:<br><tt>Grid Inch;</tt><br><tt>Set Width_Menu 0.1 0.2 0.3;</tt></td></tr>
<tr><td>Bend angle for wires </td><td width=20><td><tt>SET WIRE_BEND bend_nr;</tt></td></tr>
<tr><td> </td><td width=20><td><i>bend_nr</i> can be one of:</td></tr>
<tr><td> </td><td width=20><td><tt>0</tt>: Starting point - horizontal - vertical - end</td></tr>
<tr><td> </td><td width=20><td><tt>1</tt>: Starting point - horizontal - 45&deg; - end</td></tr>
<tr><td> </td><td width=20><td><tt>2</tt>: Starting point - end (straight connection)</td></tr>
<tr><td> </td><td width=20><td><tt>3</tt>: Starting point - 45&deg; - horizontal - end</td></tr>
<tr><td> </td><td width=20><td><tt>4</tt>: Starting point - vertical - horizontal - end</td></tr>
<tr><td> </td><td width=20><td><tt>5</tt>: Starting point - arc - horizontal - end</td></tr>
<tr><td> </td><td width=20><td><tt>6</tt>: Starting point - horizontal - arc - end</td></tr>
<tr><td> </td><td width=20><td><tt>7</tt>: "Freehand" (arc that fits to wire at start, straight otherwise)</td></tr>
<tr><td> </td><td width=20><td><tt>8</tt>: Route short end of airwire in <a href=#89>Follow-me router</a></td></tr>
<tr><td> </td><td width=20><td><tt>9</tt>: Route both ends of airwire in <a href=#89>Follow-me router</a></td></tr>
<tr><td> </td><td width=20><td>Note that <tt>0</tt>, <tt>1</tt>, <tt>3</tt> and <tt>4</tt> may contain additional miter wires (see <a href=#66>MITER</a>).</td></tr>
<tr><td> </td><td width=20><td><tt>SET WIRE_BEND @ bend_nr ...;</tt></td></tr>
<tr><td> </td><td width=20><td>Defines the bend angles that shall be actually used when switching with the right mouse button.</td></tr>
<tr><td> </td><td width=20><td><tt>SET WIRE_BEND @;</tt></td></tr>
<tr><td> </td><td width=20><td>Switches back to using all bend angles.</td></tr>
<tr><td>Beep on/off </td><td width=20><td><tt>SET BEEP OFF | ON;</tt></td></tr>
</table>
<h2>Screen display</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Color for grid lines</td><td width=20><td><tt>SET COLOR_GRID color;</tt></td></tr>
<tr><td>Layer color </td><td width=20><td><tt>SET COLOR_LAYER layer color;</tt></td></tr>
<tr><td>Fill pattern for layer </td><td width=20><td><tt>SET FILL_LAYER layer fill;</tt></td></tr>
<tr><td>Grid parameters </td><td width=20><td><tt>SET MIN_GRID_SIZE pixels;</tt></td></tr>
<tr><td> </td><td width=20><td>The grid is only displayed if the grid size is greater than the set number of pixels.</td></tr>
<tr><td>Min. text size shown </td><td width=20><td><tt>SET MIN_TEXT_SIZE size;</tt></td></tr>
<tr><td> </td><td width=20><td>Text less than <tt>size</tt> pixels high is shown as a rectangle on the screen. The setting <tt>0</tt> means that all text will be displayed readably.</td></tr>
<tr><td>Net wire display </td><td width=20><td><tt>SET NET_WIRE_WIDTH width;</tt></td></tr>
<tr><td>Pad display </td><td width=20><td><tt>SET DISPLAY_MODE REAL | NODRILL;</tt></td></tr>
<tr><td> </td><td width=20><td>REAL: Pads are displayed as they will be plotted.<br>NODRILL: Pads are shown without drill hole.</td></tr>
<tr><td> </td><td width=20><td><tt>SET PAD_NAMES OFF | ON;</tt></td></tr>
<tr><td> </td><td width=20><td>Pad names are displayed/not displayed.</td></tr>
<tr><td>Bus line display </td><td width=20><td><tt>SET BUS_WIRE_WIDTH width;</tt></td></tr>
<tr><td><a href=#46>DRC</a>-Parameter </td><td width=20><td><tt>SET DRC_FILL fill_name;</tt></td></tr>
<tr><td>Polygon calculation </td><td width=20><td><tt>SET POLYGON_RATSNEST OFF | ON;</tt></td></tr>
<tr><td> </td><td width=20><td>See <a href=#77>POLYGON</a> command.</td></tr>
<tr><td>Vector font </td><td width=20><td><tt>SET VECTOR_FONT OFF | ON;</tt></td></tr>
<tr><td> </td><td width=20><td>See <a href=#99>TEXT</a> command.</td></tr>
<tr><td>Cross-reference labels </td><td width=20><td><tt>SET XREF_LABEL_FORMAT string;</tt></td></tr>
<tr><td> </td><td width=20><td>See <a href=#60>LABEL</a> command.</td></tr>
<tr><td>Part cross-references </td><td width=20><td><tt>SET XREF_PART_FORMAT string;</tt></td></tr>
<tr><td> </td><td width=20><td>See <a href=#99>TEXT</a> command.</td></tr>
</table>
<h2>Mode parameters</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Package check </td><td width=20><td><tt>SET CHECK_CONNECTS OFF | ON;</tt></td></tr>
<tr><td> </td><td width=20><td>The <a href=#29>ADD</a> command checks whether a pin has been connected to every pad (with <a href=#40>CONNECT</a>). This check can be switched off. Nevertheless, no board can be generated from a schematic if a device is found which does not have a package.</td></tr>
<tr><td><a href=#86>REPLACE</a> mode </td><td width=20><td><tt>SET REPLACE_SAME NAMES | COORDS;</tt></td></tr>
<tr><td><a href=#100>UNDO</a> buffer on/off </td><td width=20><td><tt>SET UNDO_LOG OFF | ON;</tt></td></tr>
<tr><td>Wire optim. on/off </td><td width=20><td><tt>SET OPTIMIZING OFF | ON;</tt></td></tr>
<tr><td> </td><td width=20><td>If set <i>on</i>, wires which lie in one line after a MOVE, ROUTE or SPLIT are subsumed into a single wire. See also <a href=#71>OPTIMIZE</a>.</td></tr>
</table>
<h2>Colors</h2>
There are three <i>palettes</i> for black, white and colored background,
respectively. Each palette has 64 color entries, which can be set to any
ARGB value. The palette entry number 0 is used as the background color
(in the "white" palette this entry cannot be modified, since this palette
will also be used for printing, where the background is always white).
<p>
The color palettes can be modified either through the dialog under
"Options/Set.../Colors" or by using the command
<pre>
SET PALETTE <i>index</i> <i>argb</i>
</pre>
where <i>index</i> is a number in the range 0..63 and <i>argb</i> is a hexadecimal
value defining the Alpha, Red, Green and Blue components of the color, like 0xFFFFFF00
(which would result in a bright yellow). The alpha component defines how "opaque"
the color is. A value of 0x00 means it is completely transparent (i.e. invisible),
while 0xFF means it is totally opaque.
The alpha component of the background color is always 0xFF.
Note that the ARGB value must begin with "0x", otherwise it would be taken as a
decimal number. You can use
<pre>
SET PALETTE BLACK|WHITE|COLORED
</pre>
to switch to the black, white or colored background palette, respectively.
Note that there will be no automatic window refresh after this command, so
you should do a WINDOW; command after this.
<p>
By default only the palette entries 0..15 are used and they contain the
colors listed below.
<p>
The palette entries are grouped into "normal" and "highlight" colors. There
are always 8 "normal" colors, followed by the corresponding 8 "highlight"
colors. So colors 0..7 are "normal" colors, 8..15 are their "highlight"
values, 16..23 are another 8 "normal" colors with 24..31 being their
"highlight" values and so on. The "highlight" colors are used to visualize
objects, for instance in the SHOW command.
<p>
<tt>Color</tt>, listed according to color numbers, which can be used instead of the color names. Used to specify colors:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>0 </td><td width=20><td>Black</td></tr>
<tr><td>1 </td><td width=20><td>Blue</td></tr>
<tr><td>2 </td><td width=20><td>Green</td></tr>
<tr><td>3 </td><td width=20><td>Cyan</td></tr>
<tr><td>4 </td><td width=20><td>Red</td></tr>
<tr><td>5 </td><td width=20><td>Magenta</td></tr>
<tr><td>6 </td><td width=20><td>Brown</td></tr>
<tr><td>7 </td><td width=20><td>LGray</td></tr>
<tr><td>8 </td><td width=20><td>DGray</td></tr>
<tr><td>9 </td><td width=20><td>LBlue</td></tr>
<tr><td>10 </td><td width=20><td>LGreen</td></tr>
<tr><td>11 </td><td width=20><td>LCyan</td></tr>
<tr><td>12 </td><td width=20><td>LRed</td></tr>
<tr><td>13 </td><td width=20><td>LMagenta</td></tr>
<tr><td>14 </td><td width=20><td>Yellow</td></tr>
<tr><td>15 </td><td width=20><td>White</td></tr>
</table>
<p>
<tt>Fill</tt> specifies the style with which wires and rectangles in a particular layer are to be filled. This parameter can also be replaced with the number at the beginning of each line:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>0 </td><td width=20><td>Empty</td></tr>
<tr><td>1 </td><td width=20><td>Solid</td></tr>
<tr><td>2 </td><td width=20><td>Line</td></tr>
<tr><td>3 </td><td width=20><td>LtSlash</td></tr>
<tr><td>4 </td><td width=20><td>Slash</td></tr>
<tr><td>5 </td><td width=20><td>BkSlash</td></tr>
<tr><td>6 </td><td width=20><td>LtBkSlash</td></tr>
<tr><td>7 </td><td width=20><td>Hatch</td></tr>
<tr><td>8 </td><td width=20><td>XHatch</td></tr>
<tr><td>9 </td><td width=20><td>Interleave</td></tr>
<tr><td>10 </td><td width=20><td>WideDot</td></tr>
<tr><td>11 </td><td width=20><td>CloseDot</td></tr>
<tr><td>12 </td><td width=20><td>Stipple1</td></tr>
<tr><td>13 </td><td width=20><td>Stipple2</td></tr>
<tr><td>14 </td><td width=20><td>Stipple3</td></tr>
<tr><td>15 </td><td width=20><td>Stipple4</td></tr>
</table>
<h2>EagleRc Parameters</h2>
Sometimes a small detail of functionality needs to be made adjustable, for
instance because some users absolutely need to have it work differently.
These parameters are not available in any dialogs, but can only be changed
through an entry in the eaglerc file. In order to make this easier, any
parameter that is not found amoung the keywords listed above will be looked
up in the eaglerc parameters and can thus be changed using the SET command.
Note that the parameter names must be written in full and exactly as
listed below (case sensitive). The parameter value is typically '0' or '1',
to turn the functionality 'off' or 'on', respectively. After changing any
of these parameters that influence the way the screen display is drawn, a
window refresh may be necessary.
<p>
<b>Example</b>
<pre>
SET Option.DrawUnprocessedPolygonEdgesContinuous 1;
</pre>
The following eaglerc parameters parameters are available:
<p>
<dl>
<dt><b>Cmd.Delete.WireJointsWithoutCtrl</b>
<dd>
If you insist on having the DELETE command delete wire joints
without pressing the Ctrl key, you can set this parameter to '1'.
<dt><b>Cmd.Wire.IgnoreCtrlForRadiusMode</b>
<dd>
If you don't like the special mode in wire drawing commands that allows
for the definition of an arc radius by pressing the Ctrl key when placing
the wire, you can set this parameter to '1'.
This will turn this feature off for all commands that draw wires.
<dt><b>ControlPanel.View.AutoOpenProjectFolder</b>
<dd>
The automatic opening of the project folder at program start (or when
activating a project by clicking on its gray button) can be disabled
by setting this parameter to '0'.
<dt><b>Erc.AllowUserOverrideConsistencyCheck</b>
<dd>
In order to handle board/schematic pairs that have only minor inconsistencies,
the user can enable a dialog that allows him to force the editor to
perform forward-/backannotation, even if the ERC detects that the files are
inconsistent. This can be done by setting this parameter to '1'.
<b>PLEASE NOTE THAT YOU ARE DOING THIS AT YOUR OWN RISK</b> - if the files get
corrupted in the process, there may be nothing anybody can do to recover
them. After all, the ERC <b>did</b> state that the files were inconsistent!
<dt><b>Interface.MouseButtonReleaseTimeout</b>
<dd>
The time (in milliseconds) within which a mouse button release that follows
a mouse button press on a button (like, for instance, toolbar buttons)
triggers the button's action, even if the mouse button release happened
outside the button's area. Default is 500, set this to 0 to turn off this
feature. If this parameter is 0 when the program is started, any change
to it will only take effect the next time the program is started.
<dt><b>Interface.PreferredUnit</b>
<dd>
When displaying a numerical value in dialog input fields, the units are determined
automatically, so that the representation with the least number of decimal
digits is chosen. This can be controlled by setting this parameter to
'0' for automatic unit determination (default),
'1' for imperial units, and
'2' for metric units.
<dt><b>Interface.UseCtrlForPanning</b>
<dd>
Panning is done by moving the mouse while holding the center mouse button
(or mouse wheel) down. In older versions this was done by pressing the Ctrl
key instead. If you want the old functionality back, you can set this
parameter to '1'.
Note, though, that the Ctrl key is now used for special functions in some
commands, so when using these special functions (like selecting an object
at its origin in MOVE) with this parameter enabled you may inadvertently
pan your draw window.
<dt><b>Option.DrawUnprocessedPolygonEdgesContinuous</b>
<dd>
If you don't like the way unprocessed polygons display their edges (as dotted lines),
you can set this parameter to '1'. The edges of unprocessed polygons will then be
displayed as continuous lines, as was the case before version 5 (however, they will
not be highlighted).
<dt><b>Option.LayerSequence</b>
<dd>
The internal layers are rendered in a sequence that mimics the actual layer
stack, so that the result looks useful even on printers and PDF or Postscript
files, where layers are not transparent. Sometimes user defined layers may need to
be rendered before internal layers instead of after them. This parameter can be
used to define the sequence in which layers are rendered. It consists of a string of
layer numbers or layer ranges, followed by an optional 't' or 'b'.
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>123</td> <td width=20><td>renders layer 123</td></tr>
<tr><td>123t</td><td width=20><td>renders layer 123 if the output is "viewed from top" (not mirrored)</td></tr>
<tr><td>123b</td><td width=20><td>renders layer 123 if the output is "viewed from bottom" (mirrored)</td></tr>
<tr><td>123-140</td><td width=20><td>renders layers 123 through 140 in the given sequence</td></tr>
<tr><td>140-123</td><td width=20><td>renders layers 140 through 123 in the given sequence</td></tr>
<tr><td>*</td><td width=20><td>inserts the default sequence of the internal layers</td></tr>
<tr><td>123b * 123t</td><td width=20><td>makes layer 123 always be rendered first</td></tr>
</table>
<dd>
Note that each layer is rendered only once, even if it is listed several times.
The default sequence of the internal layers is<br>
48t 49t 19t 47t 20t 46t 23 27 25 59 57 55 53 50 51 21 44t 45t 37 35 31 29 33 39 41 43t 18t 17t 1-16 17b 18b 43b 42 40 34 30 32 36 38 45b 44b 22 52 54 56 58 60 26 28 24 46b 20b 47b 19b 49b 48b 61-99.<br>
When viewed from top, the layer sequence is rendered from right to left, while
when viewed from bottom (mirrored) it is rendered from left to right. For instance,
layer 48 (Document) is entered as 48t and 48b to always have it rendered as the last one.
Layers 21 (tPlace) and 22 (bPlace), on the other hand, are listed only once, to have
them rendered at the proper place, depending on whether the output is mirrored or not.<br>
Any layers that are not explicitly mentioned in the layer sequence are rendered after
the given sequence in ascending order.
<dt><b>Option.RatsnestLimit</b>
<dd>
The RATSNEST command processes all points of a signal, even if that
signal is very complex (in previous versions it dropped wire end points
from processing if the total number of connection points exceeded 254).
This requires more memory when calculating the ratsnest. In case this
is a problem on your system, you can revert to the original method
by setting this parameter to '254'. The value given
here is the number of connection points up to which all wire end points
will be taken into account and thus limits the amount of memory used
(processing will use up to the square of this value in bytes, so a value
of 1024 will limit the used memory to 1MB). A value of '0' means there is
no limit. A value of '1' will result in airwires being connected only to
pads, smds and vias.
<dt><b>Option.RepositionMouseCursorAfterContextMenu</b>
<dd>
Normally EAGLE doesn't automatically position the mouse cursor. However,
some users want the cursor to be repositioned to the point where it has been
before a context menu in the drawing editor was opened. Set this parameter to
'1' to get this functionality.
<dt><b>Option.ShowPartOrigins</b>
<dd>
The origins of parts in a schematic are indicated by small crosses.
Set this parameter to '0' to turn this off.
<dt><b>Option.ShowTextOrigins</b>
<dd>
The origins of texts are indicated by small crosses.
Set this parameter to '0' to turn this off.
<dt><b>Option.ToggleCtrlForGroupSelectionAndContextMenu</b>
<dd>
Since the context menu function on the right mouse button interferes
with the selection of groups as it was done before version 5, a group is
now selected with Ctrl plus right mouse button. If you want to have the old
method of selecting groups back, you can can set this parameter to '1'.
This will allow selecting groups with the right mouse button only and require
Ctrl plus right mouse button for context menus.
<dt><b>Sch.Cmd.Add.AlwaysUseDeviceNameAsValue</b>
<dd>
Some users always want to use the device name as part value, even if the
part needs a user supplied value. Those who want this can set this
parameter to '1'.
<dt><b>Warning.PartHasNoUserDefinableValue</b>
<dd>
If you don't want the warning message about a part not having a user
definable value, you can turn it off by setting this parameter to '0'.
<dt><b>Warning.SupplyPinAutoOverwriteGeneratedNetName</b>
<dd>
Some users don't want the warning message about a supply pin overwriting
a generated net name. Setting this option to '1' disables that warning.
</dl>
<a name=93>
<h1>SHOW</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Highlights objects.
<dt>
<b>Syntax</b>
<dd>
<tt>SHOW &#149;..</tt><br>
<tt>SHOW name..</tt><br>
<tt>SHOW @ name..</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Ctrl+Left</mb> toggles the show state of the selected object.
</dl>
<b>See also</b> <a href=#57>INFO</a>
<p>
The SHOW command is used to highlight objects.
Details are listed in the status bar.
Complete signals and nets can be highlighted with the SHOW command.
If a bus is selected, all nets belonging to that bus will also be
highlighted.
<h2>Cross Probing</h2>
With active <a href=#341>Forward&amp;Back Annotation</a> an object
that is highlighted with the SHOW command in a board will also be
highlighted in the schematic, and vice versa.
<h2>Different Objects</h2>
If you select different objects with the SHOW command every single
object is highlighted separately.
You can select more than one object for highlighting by pressing the
Ctrl key when clicking on the objects. When you click on an object that
is already highlighted with the Ctrl key pressed, that object will
be displayed non-highlighted again.
<p>
If several names are entered in one line, all matching objects are
highlighted at the same time.
<h2>Small Objects</h2>
If the <tt>@</tt> character is given in the command line, a pointer rectangle
is drawn around the shown object. This is helpful in locating small objects that
wouldn't show up too well just through highlighting. If more than one object is
shown, the rectangle is drawn around all the objects. It may be necessary to
zoom out (or do a WINDOW FIT command) in order to see the pointer.
If an object with the literal name <tt>@</tt> shall be shown, the name must
be enclosed in single quotes.
<h2>Wildcards</h2>
If a <tt>name</tt> parameter is given, the characters <tt>'*'</tt>, <tt>'?'</tt>
and <tt>'[]'</tt> are <i>wildcards</i> and have the following meaning:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>*</tt> </td><td width=20><td>matches any number of any characters</td></tr>
<tr><td><tt>?</tt> </td><td width=20><td>matches exactly one character</td></tr>
<tr><td><tt>[...]</tt> </td><td width=20><td>matches any of the characters between the brackets</td></tr>
</table>
<p>
If any of these characters shall be matched exactly as such, it has to be enclosed
in brackets. For example, <tt>abc[*]ghi</tt> would match <tt>abc*ghi</tt> and not
<tt>abcdefghi</tt>.
<p>
A range of characters can be given as <tt>[a-z]</tt>, which results in any character
in the range <tt>'a'</tt>...<tt>'z'</tt>.
<p>
The special pattern <tt>[number..number]</tt> forms a <a href=#35>bus name range</a>
and is therefore not treated as a wildcard pattern in a schematic.
<h2>Objects on different Sheets</h2>
If an object given by name is not found on the current schematic sheet, a dialog
is presented containing a list of sheets on which the object is found. If the object
is not found on any sheet, the sheet number is '-' in this list. Note that this
dialog only appears if any of the objects given by name (or wildcards) is not found
on the current sheet. If all given objects are found on the current sheet, no dialog
appears (even if some of the objects are also present on other sheets). Once the
dialog appears, it contains all objects found, even those on the current sheet.
<h2>Examples</h2>
<pre>
SHOW IC1
</pre>
IC1 is highlighted and remains highlighted until the SHOW command is ended
or a different name is entered.
<pre>
SHOW IC*
</pre>
Highlights all objects with names starting with "IC".
<a name=94>
<h1>SIGNAL</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Defines signals.
<dt>
<b>Syntax</b>
<dd>
<tt>SIGNAL &#149; &#149;..</tt><br>
<tt>SIGNAL signal_name &#149; &#149;..</tt><br>
<tt>SIGNAL signal_name element_name pad_name..;</tt>
</dl>
<b>See also</b> <a href=#33>AUTO</a>,
<a href=#89>ROUTE</a>,
<a href=#68>NAME</a>,
<a href=#38>CLASS</a>,
<a href=#106>WIRE</a>,
<a href=#81>RATSNEST</a>,
<a href=#50>EXPORT</a>
<p>
The SIGNAL command is used to define signals (connections between
the various packages). The user must define a minimum of two element_name/pad_name
pairs, as otherwise no airwire can be generated.
<h2>Mouse Input</h2>
To do that you select (with the mouse) the pads (or smds) of the elements
to be connected, step by step. EAGLE displays the part signals as airwires
in the Unrouted layer.
<p>
If input with signal_name the signal will be allocated the specified
name.
<h2>Text Input</h2>
Signals may also be defined completely by text input (via keyboard
or script file). The command
<pre>
SIGNAL GND IC1 7 IC2 7 IC3 7;
</pre>
connects pad 7 of IC1...3. In order to enter a whole netlist, a script
file may be generated, with the extension *.scr. This file
should include all of the necessary SIGNAL commands in the format shown
above.
<h2>On-line Check</h2>
If the SIGNAL command is used to connect pads (or smds) that already
belong to different signals, a popup menu will appear and ask the
user if he wants to connect the signals together, and which name the
signal should get.
<h2>Outlines data</h2>
The special signal name _OUTLINES_ gives a signal certain properties that
are used to generate <a href=#130>outlines data</a>.
This name should not be used otherwise.
<a name=95>
<h1>SMASH</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Separates text variables and attributes from parts or elements.
<dt>
<b>Syntax</b>
<dd>
<tt>SMASH &#149;..</tt><br>
<tt>SMASH name ..</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Ctrl+Right</mb> smashes the group.<br>
<mb>Shift+Left</mb> reverses the text separation ("unsmashes" the part).<br>
<mb>Ctrl+Shift+Right</mb> reverses the text separation for the group.
</dl>
<b>See also</b> <a href=#68>NAME</a>,
<a href=#103>VALUE</a>,
<a href=#99>TEXT</a>,
<a href=#32>ATTRIBUTE</a>
<p>
The SMASH command is used with parts or elements in order to separate the text
parameters indicating name, value or attributes. The text may
then be placed in a new and more convenient location with the MOVE
command.
<p>
Parts and elements can also be selected by their name,
which is especially useful if the object is outside the currently shown
window area. Note that when selecting a multi-gate part in a schematic by name,
you will need to enter the full instance name, consisting of part
and gate name.
<p>
Use of the SMASH command allows the text to be treated like any other
text, e.g. CHANGE SIZE, ROTATE, etc., but the actual text may not
be changed.
<p>
A "smashed" element can be made "unsmashed" by clicking on it with the
<tt>Shift</tt> key pressed (and of course the SMASH command activated).
<a name=96>
<h1>SMD</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Adds smd pads to a package.
<dt>
<b>Syntax</b>
<dd>
<tt>SMD [x_width y_width] [-roundness] [orientation] [flags] ['name'] &#149;..</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Center</mb> selects the layer.<br>
<mb>Right</mb> rotates the smd.<br>
<mb>Shift+Right</mb> reverses the direction of rotating.
</dl>
<b>See also</b> <a href=#73>PAD</a>,
<a href=#36>CHANGE</a>,
<a href=#68>NAME</a>,
<a href=#89>ROUTE</a>,
<a href=#133>Design Rules</a>
<p>
The SMD command is used to add pads for surface mount devices to a
package. When the SMD command is active, an smd symbol is attached
to the cursor. Pressing the left mouse button places an smd pad at
the current position.
Entering numbers changes the x- and y-width of the smd pad, which
can be up to 0.51602 inch (13.1 mm). These parameters
remain as defaults for successive SMD commands and can be changed
with the CHANGE command. Pressing
the center mouse button changes the layer onto which the smd pad will be drawn.
<p>
The <tt>orientation</tt> (see description in <a href=#29>ADD</a>)
may be any angle in the range <tt>R0</tt>...<tt>R359.9</tt>. The <tt>S</tt>
and <tt>M</tt> flags can't be used here.
<h2>Roundness</h2>
The <tt>roundness</tt> has to be entered as an integer number between
<tt>0</tt> and <tt>100</tt>, with a negative sign to distinguish it
from the width parameters. A value of <tt>0</tt> results in fully
rectangular smds, while a value of <tt>100</tt> makes the corners
of the smd fully round. The command
<pre>
SMD 50 50 -100 '1' &#149;
</pre>
for example would create a completely round smd named '1' at the given
mouseclick position. This can be used to create BGA (Ball Grid Array) pads.
<h2>Names</h2>
SMD names are generated automatically and may be modified with the
NAME command. Names may be included
in the SMD command if enclosed in single quotes.
<h2>Flags</h2>
The following <i>flags</i> can be used to control the appearance of an smd:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>NOSTOP</tt> </td><td width=20><td>don't generate solder stop mask</td></tr>
<tr><td><tt>NOTHERMALS</tt> </td><td width=20><td>don't generate thermals</td></tr>
<tr><td><tt>NOCREAM</tt> </td><td width=20><td>don't generate cream mask</td></tr>
</table>
<p>
By default an smd automatically generates solder stop mask, cream mask and thermals as necessary.
However, in special cases it may be desirable to have particular smds not do this.
The above <tt>NO...</tt> flags can be used to suppress these features.<br>
A newly started SMD command resets all flags to their defaults. Once a flag is given
in the command line, it applies to all following smds placed within this SMD command.
<h2>Single Smds</h2>
Single smd pads in boards can only be used by defining
a package with one smd.
<h2>Alter Package</h2>
It is not possible to add or delete smds in packages which
are already used by a device, because this would change the pin/smd
allocation defined with the CONNECT command.
<a name=97>
<h1>SPLIT</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Splits wires and polygon edges into segments.
<dt>
<b>Syntax</b>
<dd>
<tt>SPLIT &#149; [curve | @radius] &#149;..</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Right</mb> changes the wire bend style (see <a href=#92>SET Wire_Bend</a>).<br>
<mb>Shift+Right</mb> reverses the direction of switching bend styles.<br>
<mb>Ctrl+Right</mb> toggles between corresponding bend styles.<br>
<mb>Ctrl+Left</mb> when placing a wire end point defines arc radius.
<dt>
<b>Keyboard</b>
<dd>
<tt>F8: SPLIT</tt> activates the SPLIT command.
</dl>
<b>See also</b> <a href=#66>MITER</a>,
<a href=#67>MOVE</a>,
<a href=#71>OPTIMIZE</a>,
<a href=#92>SET</a>
<p>
The SPLIT command is used to split a wire (or segment) or a polygon
edge into two segments in order, for example, to introduce a bend.
This means you can split wires into parts that can be moved with the
mouse during the SPLIT command. A mouseclick defines the point at
which the wire is split. The shorter of the two new segments follows
the current wire bend rules and may therefore itself become two segments
(see SET Wire_Bend), the longer segment is a straight segment running
to the next end point.
<p>
If the <i>curve</i> or <i>@radius</i> parameter is given, an arc can be drawn as part of the wire segment
(see the detailed description in the <a href=#106>WIRE</a> command).
<p>
On completion of the SPLIT command, the segments are automatically
rejoined if they are in line unless the command
<pre>
SET OPTIMIZING OFF;
</pre>
has previously been given, or the wire has been clicked at the same
spot twice. In this case the split points remain and can be used,
for example, to <b>reduce the width of a segment</b>. This is achieved by
selecting the SPLIT command, marking the part of the wire which is
to be reduced with two mouse clicks, and using the command
<pre>
CHANGE WIDTH width
</pre>
The segment is then clicked on to complete the change.
<a name=98>
<h1>TECHNOLOGY</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Defines the possible <i>technology</i> parts of a device name.
<dt>
<b>Syntax</b>
<dd>
<tt>TECHNOLOGY name ..;</tt><br>
<tt>TECHNOLOGY -name ..;</tt><br>
<tt>TECHNOLOGY -* ..;</tt>
</dl>
<b>See also</b> <a href=#72>PACKAGE</a>,
<a href=#32>ATTRIBUTE</a>
<p>
This command is used in the device editor mode to define the possible <i>technology</i>
parts of a device name.
In the schematic or board editor the TECHNOLOGY command behaves exactly
like "<a href=#36>CHANGE TECHNOLOGY</a>".
<p>
Exactly one of the names given in the TECHNOLOGY command will
be used to replace the <tt>'*'</tt> in the device set name when an actual device is added
to a schematic.
The term <i>technology</i> stems from the main usage of this feature in creating
different variations of the same basic device, which all have the same schematic
symbol(s), the same package and the same pin/pad connections. They only differ in
a part of their name, which for the classic TTL devices is related to their
different technologies, like "L", "LS" or "HCT".
<p>
The TECHNOLOGY command can only be used if a package variant has been selected with the <a href=#72>PACKAGE</a> command.
<p>
If no <tt>'*'</tt> character is present in the device set name, the technology will
be appended to the device set name to form the full device name. Note that the technology
is processed before the package variant, so if the device set name contains neither
a <tt>'*'</tt> nor a <tt>'?'</tt> character, the resulting device name will consist
of <i>device_set_name</i><tt>+</tt><i>technology</i><tt>+</tt><i>package_variant</i>.
<p>
The names listed in the TECHNOLOGY command will be added to an already existing list
of technologies for the current device.
Starting a name with <tt>'-'</tt> will remove that name from the list of technologies.
If a name shall begin with <tt>'-'</tt>, it has to be enclosed in single quotes.
Using <tt>-*</tt> removes all technologies.
<p>
Only ASCII characters in the range 33..126 may be used in technologies (lowercase characters
will be converted to uppercase), and the maximum number of technologies per device is 254.
<p>
The special "empty" technology can be entered as two single quotes (<tt>''</tt>, an empty string).
<p>
Note that the Technologies dialog contains all technologies from all devices in
the loaded library, with the ones referenced by the current device checked.
<h2>Example</h2>
In a device named "<tt>74*00</tt>" the command
<pre>
TECHNOLOGY -* '' L LS S HCT;
</pre>
would first remove any existing technologies and then create the individual technology variants
<pre>
7400
74L00
74LS00
74S00
74HCT00
</pre>
<a name=99>
<h1>TEXT</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Adds text to a drawing.
<dt>
<b>Syntax</b>
<dd>
<tt>TEXT any_text orientation &#149;..</tt><br>
<tt>TEXT 'any_text' orientation &#149;..</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Center</mb> selects the layer.<br>
<mb>Right</mb> rotates the text.<br>
<mb>Shift+Right</mb> reverses the direction of rotating.
</dl>
<b>See also</b> <a href=#36>CHANGE</a>,
<a href=#67>MOVE</a>,
<a href=#65>MIRROR</a>,
<a href=#75>PIN</a>,
<a href=#88>ROTATE</a>,
<a href=#32>ATTRIBUTE</a>
<p>
The TEXT command is used to add text to a library element or drawing.
When entering several texts it is not necessary to invoke the
command each time, as the text command remains active after placing
text with the mouse.
<h2>Orientation</h2>
The orientation of the text may be defined by the TEXT command (orientation)
using the usual definitions as listed in the <a href=#29>ADD</a> command (R0, R90
etc.). The right mouse button will change the rotation of the text
and the center mouse button will change the current layer.
<p>
Text is always displayed so that it can be read from in front or from
the right - even if rotated. Therefore after every two rotations it
appears the same way, but the origin has moved from the lower left
to the upper right corner. Remember this if a text appears to be unselectable.
<p>
If you want to have text that is printed "upside down", you can set the "Spin"
flag for that text.
<h2>Special Characters</h2>
If the text contains several successive blanks or a semicolon, the
whole string has to be enclosed in single quotes. If the text contains
single quotes then each one itself has to be enclosed in single quotes.
If apostrophes are required in the text, each must be enclosed
in single quotes.
<h2>Key Words</h2>
If the TEXT command is active and you want to type in a text that
contains a string that can be mistaken for a command (e.g. "red"
for "REDO") then this string has to be enclosed in single
quotes.
<h2>Text Height</h2>
The height of characters and the line width can be changed with the
CHANGE commands:
<pre>
CHANGE SIZE text_size &#149;..
CHANGE RATIO ratio &#149;..
</pre>
Maximum text height: 2 inches<br>
Maximum line width: 0.51602 inch (13.1 mm)<br>
Ratio: 0...31 (% of text height).
<h2>Text Font</h2>
Texts can have three different fonts:
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>Vector</tt></td> <td width=20><td>the program's internal vector font</td></tr>
<tr><td><tt>Proportional</tt></td> <td width=20><td>a proportional pixel font (usually 'Helvetica')</td></tr>
<tr><td><tt>Fixed</tt></td> <td width=20><td>a monospaced pixel font (usually 'Courier')</td></tr>
</table>
<p>
The text font can be changed with the CHANGE command:
<pre>
CHANGE FONT VECTOR|PROPORTIONAL|FIXED &#149;..
</pre>
The program makes great efforts to output texts with fonts other than
<tt>Vector</tt> as good as possible. However, since the actual font is drawn
by the system's graphics interface, <tt>Proportional</tt> and <tt>Fixed</tt> fonts
may be output with different sizes and/or lengths.
<p>
If you set the option "Always vector font" in the <a href=#16>user interface dialog</a>,
all texts will always be displayed and printed using the builtin vector font.
This option is useful if the system doesn't display the other fonts correctly.<br>
When creating a new board or schematic, the current setting of this option is stored in the
drawing file. This makes sure that the drawing will be printed with the correct
setting if it is transferred to somebody else who has a different setting of
this option.<br>
You can use the <tt><a href=#92>SET</a> VECTOR_FONT OFF|ON</tt> command
to change the setting in an existing board or schematic drawing.
<p>
When creating output files with the CAM Processor, texts will always be drawn with
<tt>Vector</tt> font. Other fonts are not supported.
<p>
If a text with a font other than <tt>Vector</tt> is subtracted from a signal
polygon, only the surrounding rectangle is subtracted. Due to the
above mentioned possible size/length problems, the actually printed
font may exceed that rectangle. Therefore, if you need to subtract
a text from a signal polygon it is recommended that you use the <tt>Vector</tt>
font.
<p>
The <i>Ratio</i> parameter has no meaning for texts with fonts other than <tt>Vector</tt>.
<h2>Character Sets</h2>
Only the characters with ASCII codes below 128 are guaranteed to be printed correctly.
Any characters above this may be system dependent and may yield different results
with the various fonts.
<h2>Text Variables</h2>
Special texts in a symbol or package drawing, marked with the <tt>'&gt;'</tt>
character, will be replaced with actual values in a board or schematic:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>&gt;NAME</tt> </td><td width=20><td>Component name (ev.+gate name) 1)</td></tr>
<tr><td><tt>&gt;VALUE</tt> </td><td width=20><td>Comp. value/type 1)</td></tr>
<tr><td><tt>&gt;PART</tt> </td><td width=20><td>Component name 2)</td></tr>
<tr><td><tt>&gt;GATE</tt> </td><td width=20><td>Gate name 2)</td></tr>
<tr><td><tt>&gt;XREF</tt> </td><td width=20><td>Part cross-reference 2)</td></tr>
<tr><td><tt>&gt;CONTACT_XREF</tt> </td><td width=20><td>Contact cross-reference 2)</td></tr>
<tr><td><tt>&gt;DRAWING_NAME</tt> </td><td width=20><td>Drawing name</td></tr>
<tr><td><tt>&gt;LAST_DATE_TIME</tt> </td><td width=20><td>Time of the last modification</td></tr>
<tr><td><tt>&gt;PLOT_DATE_TIME</tt> </td><td width=20><td>Time of the plot creation</td></tr>
<tr><td><tt>&gt;SHEETNR</tt> </td><td width=20><td>Sheet number of a schematic 3)</td></tr>
<tr><td><tt>&gt;SHEETS</tt> </td><td width=20><td>Total number of sheets of a schematic 3)</td></tr>
<tr><td><tt>&gt;SHEET</tt> </td><td width=20><td>equivalent to "&gt;SHEETNR/&gt;SHEETS" 3)</td></tr>
</table>
<p>
1) Only for package or symbol<br>
2) Only for symbol<br>
3) Only for symbol or schematic
<p>
The format in which a part cross-reference is displayed can be controlled
through the "Xref part format" string, which is defined in the "Options/Set/Misc"
dialog, or with the <a href=#92>SET</a> command.
The following placeholders are defined, and can be used in any order:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>%S</tt></td> <td width=20><td>the sheet number</td></tr>
<tr><td><tt>%C</tt></td> <td width=20><td>the column on the sheet</td></tr>
<tr><td><tt>%R</tt></td> <td width=20><td>the row on the sheet</td></tr>
</table>
<p>
The default format string is <tt>"/%S.%C%R"</tt>. Apart from the defined
placeholders you can also use any other ASCII characters.
<h2>Attributes</h2>
If a symbol or package drawing shall display an <a href=#32>attribute</a>
of the actual part or element, a text with the name of that attribute, marked with
the <tt>'&gt;'</tt> character, can be used. By default, only the actual value of the
given attribute will be displayed. If the attribute name is followed by one of the
special characters <tt>'='</tt>, <tt>'~'</tt> or <tt>'!'</tt>, the actual display
is as follows:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td with=100><tt>&gt;ABC </tt></td><td width=20><td><tt>123</tt></td></tr>
<tr><td><tt>&gt;ABC=</tt></td><td width=20><td><tt>ABC = 123</tt></td></tr>
<tr><td><tt>&gt;ABC~</tt></td><td width=20><td><tt>ABC</tt></td></tr>
<tr><td><tt>&gt;ABC!</tt></td><td width=20><td><tt><i>nothing</i></tt></td></tr>
</table>
<h2>Overlined text</h2>
Text can be <i>overlined</i>, which is useful for instance for the names of inverted
signals ("active low", see also
<a href=#69>NET</a>, <a href=#35>BUS</a> and <a href=#75>PIN</a>).
To do so, the text needs to be preceded with an exclamation mark (<tt>'!'</tt>), as in
<pre>
!RESET
</pre>
which would result in
<pre>
_____
RESET
</pre>
This is not limited to signal names, but can be used in any text. It is
also possible to overline only part of a text, as in
<pre>
!RST!/NMI
R/!W
</pre>
which would result in
<pre>
___
RST/NMI
_
R/W
</pre>
Note that the second exclamation mark indicates the end of the overline.
There can be any number of overlines in a text. If a text shall contain
an exclamation mark that doesn't generate an overline, it needs to be
escaped by a backslash. In order to keep the need for escaping exclamation
marks at a minimum, an exclamation mark doesn't start an overline if it
is the last character of a text, or if it is immediately followed by a
blank, another exclamation mark, a double or single quote, or by a right
parenthesis, bracket or brace. Any non-escaped exclamation mark or comma
that appears after an exclamation mark that started an overline will end
the overline (the comma as an overline terminator is necessary for busses).
<a name=100>
<h1>UNDO</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Cancels previous commands.
<dt>
<b>Syntax</b>
<dd>
<tt>UNDO;</tt>
<dt>
<b>Keyboard</b>
<dd>
<tt>F9: UNDO</tt> execute the UNDO command.
<tt>Alt+BS: UNDO</tt>
</dl>
<b>See also</b> <a href=#83>REDO</a>,
<a href=#92>SET</a>,
<a href=#341>Forward&amp;Back Annotation</a>
<p>
The UNDO command allows you to cancel previously executed commands.
This is especially useful if you have deleted things by accident.
Multiple UNDO commands cancel the corresponding number of commands
until the last EDIT, OPEN, AUTO, or REMOVE command is reached. It
is not possible to "undo" window operations.
<p>
The UNDO command uses up disk space. If you are short of
this you can switch off this function with the SET command
<pre>
SET UNDO_LOG OFF;
</pre>
UNDO/REDO is completely integrated within Forward&amp;Back Annotation.
<a name=101>
<h1>UPDATE</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Updates library objects.
<dt>
<b>Syntax</b>
<dd>
<tt>UPDATE</tt><br>
<tt>UPDATE;</tt><br>
<tt>UPDATE library_name..;</tt><br>
<tt>UPDATE package_name@library_name..;</tt><br>
<tt>UPDATE +@ | -@ [library_name..];</tt><br>
<tt>UPDATE old_library_name = new_library_name;</tt>
</dl>
<b>See also</b> <a href=#29>ADD</a>,
<a href=#86>REPLACE</a>
<p>
The UPDATE command checks the parts in a board or schematic against
their respective library objects and automatically updates them if
they are different. If UPDATE is invoked from the library editor, the
packages within the loaded library will be updated from the given
libraries.
<p>
If you activate the UPDATE command without a parameter, a file dialog will
be presented to select the library from which to update.
<p>
If one ore more libraries are given, only parts from those libraries will be checked.
The library names can be either a plain library name (like "ttl" or "ttl.lbr") or a full
file name (like "/home/mydir/myproject/ttl.lbr" or "../lbr/ttl").
<h2>Update in a board or schematic</h2>
If the command is terminated with a <tt>';'</tt>, but has no parameters,
all parts will be checked.
<p>
If the first parameter is <tt>'+@'</tt>, the names of the given libraries (or all libraries,
if none are given) will get a <tt>'@'</tt> character appended, followed by a number.
This can be used to make sure the libraries contained in a drawing will not be modified when
a part from a newer library with the same name is added to the drawing. Library names that
already end with a <tt>'@'</tt> character followed by a number will not be changed.
<p>
If the first parameter is <tt>'-@'</tt>, the <tt>'@'</tt> character (followed by a number) of the given
libraries (or all libraries, if none are given) will be stripped from the library name.
This of course only works if there is no library with that new name already in the drawing.
<p>
Please note that "UPDATE +@;" followed by "UPDATE -@;" (and vice versa) does not necessarily
result in the original set of library names, because the sequence in which the names are processed
depends on the sequence in which the libraries are stored in the drawing file.
<p>
The libraries stored in a board or schematic drawing are identified only by their
base name (e.g. "ttl"). When considering whether an update shall be performed,
only the base name of the library file name will be taken into account.
Libraries will be searched in the directories specified under "Libraries" in the
<a href=#14>directories dialog</a>, from left to right.
The first library of a given name that is found will be taken. Note that the library
names stored in a drawing are handled case insensitive. It does not matter whether
a specific library is currently "in use". If a library is not found, no update
will be performed for that library and there will be no error message.
<p>
Using the UPDATE command in a schematic or board that are connected via active
<a href=#341>Forward&amp;Back Annotation</a> will act on both the
schematic and the board.
<p>
At some point you may need to specify whether gates, pins or pads shall
be mapped by their names or their coordinates. This is the case when the respective library
objects have been renamed or moved. If too many modifications have been made (for example, if
a pin has been both renamed and moved) the automatic update may not be possible. In that case
you can either do the library modification in two steps (one for renaming, another for moving),
or give the whole library object a different name.
<p>
When used with <tt>old_library_name = new_library_name</tt> (note that there has to be
at least one blank before and after the <tt>'='</tt> character), the UPDATE command
locates the library named <i>old_library_name</i> in the current board or schematic,
and updates it with the contents of <i>new_library_name</i>. Note that <i>old_library_name</i>
must be the pure library name, without any path, while <i>new_library_name</i>
may be a full path name. If the update was performed successfully, the library in the current board/schematic file will
also be renamed accordingly - therefore this whole operation is, of course, only
possible if <i>new_library_name</i> has not yet been used in the current board or schematic.
<p>
<b>Note: You should always run a <a href=#46>Design Rule Check</a> (DRC) and an
<a href=#48>Electrical Rule Check</a> (ERC) after a library update has been performed
in a board or a schematic!</b>
<h2>Update in a library</h2>
The update in a library replaces all packages within that library with the versions
from the given libraries.
<p>
By specifying the package name (package_name@library_name) you can have only a
specific package be replaced.
<a name=102>
<h1>USE</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Marks a library for use.
<dt>
<b>Syntax</b>
<dd>
<tt>USE</tt><br>
<tt>USE -*;</tt><br>
<tt>USE library_name..;</tt>
</dl>
<b>See also</b> <a href=#29>ADD</a>,
<a href=#86>REPLACE</a>
<p>
The USE command marks a library for later use with the
<a href=#29>ADD</a> or <a href=#86>REPLACE</a> command.
<p>
If you activate the USE command without a parameter, a file dialog
will appear that lets you select a library file.
If a path for libraries has been defined in the
"Options/Directories" dialog,
the libraries from the first entry in this path are shown in the file dialog.
<p>
The special parameter <tt>-*</tt> causes all previously marked libraries
to be dropped.
<p>
<tt>library_name</tt> can be the full name of a library or it can contain
wildcards.
If <tt>library_name</tt> is the name of a directory, all libraries from
that directory will be marked.
<p>
The suffix <tt>.lbr</tt> can be omitted.
<p>
Note that when adding a device or package to a drawing, the complete library
information for that object is copied into the drawing file, so that
you don't need the library for changing the drawing later.
<p>
Changes in a library have no effect on existing drawings.
See the <a href=#101>UPDATE</a> command if you want to
update parts from modified libraries.
<h2>Using Libraries via the Control Panel</h2>
Libraries can be easily marked for use in the <a href=#12>Control Panel</a>
by clicking on their activation icon (which changes its color to indicate that this
library is being used), or by selecting "Use" from the library's context menu.
Through the context menu of the "Libraries" entry in the Control Panel it is also
possible to use <i>all</i> of the libraries or <i>none</i> of them.
<h2>Used Libraries and Projects</h2>
The libraries that are currently in use will be stored in the project file
(if a project is currently open).
<h2>Examples</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>USE</tt> </td><td width=20><td>opens the file dialog to choose a library</td></tr>
<tr><td><tt>USE -*;</tt> </td><td width=20><td>drops all previously marked libraries</td></tr>
<tr><td><tt>USE demo trans*;</tt> </td><td width=20><td>marks the library demo.lbr and all libraries with names matching trans*.lbr</td></tr>
<tr><td><tt>USE -* /eagle/lbr;</tt> </td><td width=20><td>first drops all previously marked libraries and then marks all libraries from the directory /eagle/lbr</td></tr>
</table>
<a name=103>
<h1>VALUE</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Displays and changes values.
<dt>
<b>Syntax</b>
<dd>
<tt>VALUE &#149;..</tt><br>
<tt>VALUE value &#149;..</tt><br>
<tt>VALUE name value ..</tt><br>
<tt>VALUE ON;</tt><br>
<tt>VALUE OFF;</tt>
</dl>
<b>See also</b> <a href=#68>NAME</a>,
<a href=#95>SMASH</a>
<h2>In Boards and Schematics</h2>
Elements can be assigned a value, e.g. '1k' for a resistor or '10uF'
for a capacitor. This is done with the VALUE command. The
command selects an element and opens a popup menu that allows you
to enter or to change a value.
<p>
If you type in a value before you select an element, then all of the subsequently
selected elements receive this value. This is very useful if you want
for instance a number of resistors to have the same value.
<p>
If the parameters name and value are specified, the
element name gets the specified value.
<h2>Example</h2>
<pre>
VALUE R1 10k R2 100k
</pre>
In this case more than one element has been assigned a value. This
possibility can be used in script files:
<pre>
VALUE R1 10k \
R2 100k \
R3 5.6k \
C1 10uF \
C2 22nF \
...
</pre>
The '\' prevents the following line from being mistaken for an EAGLE
key word.
<h2>In Device Mode</h2>
If the VALUE command is used in the device edit mode, the parameters
ON and OFF may be used:
<p>
On: Permits the actual value to be changed in the schematic.
<p>
Off: Automatically enters the actual device name into the schematic
(e.g.74LS00N). The user can only modify this value after a confirmation.
<a name=104>
<h1>VIA</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Adds vias to a board.
<dt>
<b>Syntax</b>
<dd>
<tt>VIA ['signal_name'] [diameter] [shape] [layers] [flags] &#149;..</tt>
</dl>
<b>See also</b> <a href=#96>SMD</a>,
<a href=#36>CHANGE</a>,
<a href=#45>DISPLAY</a>,
<a href=#92>SET</a>,
<a href=#73>PAD</a>,
<a href=#133>Design Rules</a>
<p>
When the VIA command is active, a via symbol is attached to the cursor.
Pressing the left mouse button places a via at the current position.
The via is added to a signal if it is placed on an existing signal wire.
If you try to connect different signals, EAGLE will ask you if you really
want to connect them.
<h2>Signal name</h2>
The <tt>signal_name</tt> parameter is intended mainly to be used in
script files that read in generated data. If a <tt>signal_name</tt>
is given, all subsequent vias will be added to that signal, and no
automatic checks will be performed.<br>
<b>This feature should be used with great care because it could result
in short circuits, if a via is placed in a way that it would connect
wires belonging to different signals. Please run a
<a href=#46>Design Rule Check</a> after using the VIA command
with the <tt>signal_name</tt> parameter!</b>
<h2>Via diameter</h2>
Entering a number changes the diameter of the via (in the actual
unit) and the value remains in use for further vias. Via diameters
can be up to 0.51602 inch (13.1 mm).
<p>
The drill diameter of the via is the same as the diameter set for
pads. It can be changed with
<pre>
CHANGE DRILL diameter &#149;
</pre>
<h2>Shape</h2>
A via can have one of the following shapes:
<p>
Square<br>
Round<br>
Octagon
<p>
These shapes only apply to the outer layers (Top and Bottom).
In inner layers the shape is always "round".
<p>
Vias generate drill symbols in the Drills layer and the solder
stop mask in the tStop/bStop layers.
<p>
Like the diameter, the via shape can be entered while
the VIA command is active, or it can be changed with the CHANGE command.
The shape then remains valid for the next vias and pads.
<p>
Note that the actual shape and diameter of a via will be determined by the
<a href=#133>Design Rules</a> of the board the via is used in.
<h2>Layers</h2>
The <tt>layers</tt> parameter defines the layers this via shall
cover. The syntax is <tt>from-to</tt>, where 'from' and 'to' are the layer numbers
that shall be covered. For instance <tt>2-7</tt> would create a via that goes from
layer 2 to layer 7 (<tt>7-2</tt> would have the same meaning). If that exact via is
not available in the layer setup of the <a href=#133>Design Rules</a>, the next longer via
will be used (or an error message will be issued in case no such via can be
set).
<h2>Flags</h2>
The following <i>flags</i> can be used to control the appearance of a via:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>STOP</tt> </td><td width=20><td>always generate solder stop mask</td></tr>
</table>
<p>
By default a via with a drill diameter that is less than or equal to the value of
the <a href=#133>Design Rules</a> parameter "Masks/Limit" will not
have a solder stop mask. The above <tt>STOP</tt> flag can be used to force a solder
stop mask for a via.
<a name=105>
<h1>WINDOW</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Zooms in and out of a drawing.
<dt>
<b>Syntax</b>
<dd>
<tt>WINDOW;</tt><br>
<tt>WINDOW &#149;;</tt><br>
<tt>WINDOW &#149; &#149;;</tt><br>
<tt>WINDOW &#149; &#149; &#149;</tt><br>
<tt>WINDOW scale_factor</tt><br>
<tt>WINDOW FIT</tt><br>
<tt>WINDOW LAST</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Left&amp;Drag</mb> defines a rectangular window (shortcut for "<tt>&#149; &#149;;</tt>").
<dt>
<b>Keyboard</b>
<dd>
<tt>Alt+F2: WINDOW FIT </tt> Fit drawing on the screen<br>
<tt>F2: WINDOW; </tt> Redraw screen<br>
<tt>F3: WINDOW 2 </tt> Zoom in by a factor of 2<br>
<tt>F4: WINDOW 0.5 </tt> Zoom out by a factor of 2<br>
<tt>F5: WINDOW (@);</tt> Cursor pos. is new center (if a command is active)
</dl>
The WINDOW command is used to zoom in and out of the drawing and to
change the position of the drawing on the screen. The command can
be used with up to three mouse clicks. If there are fewer, it must
be terminated with a semicolon.
<h2>Refresh screen</h2>
If you use the WINDOW command followed by a semicolon, EAGLE redraws
the screen without changing the center or the scale. This is useful
if error messages cover part of the drawing.
<h2>New center</h2>
The WINDOW command with one point causes that point to become
the center of a new screen display of the drawing. The scaling of
the drawing remains the same. You can also use the sliders of the
working area to move the visible area of the drawing. The function
key F5 causes the current position of the cursor to be the new center.
<h2>Corner points</h2>
The WINDOW command with two points defines a rectangle with
the specified points at opposite corners. The rectangle expands to
fill the screen providing a close-up view of the specified portion
of the drawing.
<h2>New center and zoom</h2>
You can use the WINDOW command with three points. The first
point defines the new center of the drawing and the display becomes
either larger or smaller, depending on the ratios of the spacing between
the other points. In order to zoom in, the distance between point
1 and point 3 should be greater than the distance between point 1
and 2; to zoom out place point 3 between points 1 and 2.
<h2>Zoom in and out</h2>
<pre>
WINDOW 2;
</pre>
Makes the elements appear twice as large.
<pre>
WINDOW 0.5;
</pre>
Reduces the size of the elements by a factor of two.
<p>
You can specify an integer or real number as the argument to the WINDOW
command to scale the view of the drawing by the amount entered. The
center of the window remains the same.
<h2>The whole drawing</h2>
<pre>
WINDOW FIT;
</pre>
fits the entire drawing on the screen.
<h2>Back to the previous window</h2>
<pre>
WINDOW LAST;
</pre>
switches back to the previous window selection. A window selection is stored by
every WINDOW command, except for zoom-only WINDOW commands and modifications of
the window selection with the mouse.
<h2>Very large zoom factors</h2>
By default the maximum zoom factor is limited in such a way that
an area of 1mm (about 40mil) in diameter will be shown using the full editor window.
If you need to zoom in further, you can uncheck "Options/User interface/Limit zoom factor"
and will then be able to zoom in all the way until the finest editor grid (0.1 micron)
can be seen.
<p>
When zooming very far into a drawing, the following things may happen:
<ul>
<li>Texts that are not using the vector font may not be shown if they are larger
than the editor window.
<li>Circles and Arcs are approximated and therefore may not appear at their exact
location (especially if they have a very small width).
<li>Whether or not the finest grid will be visible when zooming all the way in depends
on your screen resolution, the editor window size and the value of
"Options/Set/Misc/Min. visible grid size".
</ul>
<h2>Parameter Aliases</h2>
Parameter aliases can be used to define certain parameter settings to the
WINDOW command, which can later be referenced by a given name.
The aliases can also be accessed by clicking on the "WINDOW Select" button
and holding the mouse button pressed until the list pops up.
A right click on the button also pops up the list.
<p>
The syntax to handle these aliases is:
<dl>
<dt>
<tt>WINDOW = <i>name</i> <i>parameters</i></tt>
<dd>
Defines the alias with the given <i>name</i> to expand to the given
<i>parameters</i>. The <i>name</i> may consist of any number of letters,
digits and underlines, and is treated case insensitive. It must begin
with a letter or underline and may not be one of the option keywords.
<dt>
<tt>WINDOW = <i>name</i> @</tt>
<dd>
Defines the alias with the given <i>name</i> to expand to the current
window selection.
<dt>
<tt>WINDOW = ?</tt>
<dd>
Asks the user to enter a name for defining an alias for the current
window settings.
<dt>
<tt>WINDOW = <i>name</i></tt>
<dd>
Allows the user to select a window that will be defined as an alias
under the given <i>name</i>.
<dt>
<tt>WINDOW = <i>name</i>;</tt>
<dd>
Deletes the alias with the given <i>name</i>.
<dt>
<tt>WINDOW <i>name</i></tt>
<dd>
Expands the alias with the given <i>name</i> and executes the WINDOW command with
the resulting set of parameters. The <i>name</i> may be abbreviated and
there may be other parameters before and after the alias (even other
aliases). Note that in case <i>name</i> is an abbreviation, aliases have precedence
over other parameter names of the command.
</dl>
Example:
<p>
<tt>WINDOW = MyWindow (0 0) (4 3);</tt>
<p>
Defines the alias "MyWindow" which, when used as in
<p>
<tt>WINDOW myw</tt>
<p>
will zoom to the given window area.
Note the abbreviated use of the alias and the case insensitivity.
<a name=106>
<h1>WIRE</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Adds wires (tracks) to a drawing.
<dt>
<b>Syntax</b>
<dd>
<tt>WIRE ['signal_name'] [width] &#149; &#149;..</tt><br>
<tt>WIRE ['signal_name'] [width] [ROUND | FLAT] &#149; [curve | @radius] &#149;..</tt>
<dt>
<b>Mouse keys</b>
<dd>
<mb>Center</mb> selects the layer.<br>
<mb>Right</mb> changes the wire bend style (see <a href=#92>SET Wire_Bend</a>).<br>
<mb>Shift+Right</mb> reverses the direction of switching bend styles.<br>
<mb>Ctrl+Left</mb> when starting a wire snaps it to the next existing wire end point.<br>
<mb>Ctrl+Right</mb> toggles between corresponding bend styles.<br>
<mb>Ctrl+Left</mb> when placing a wire end point defines arc radius.
</dl>
<b>See also</b> <a href=#66>MITER</a>,
<a href=#94>SIGNAL</a>,
<a href=#89>ROUTE</a>,
<a href=#36>CHANGE</a>,
<a href=#69>NET</a>,
<a href=#35>BUS</a>,
<a href=#43>DELETE</a>,
<a href=#87>RIPUP</a>,
<a href=#30>ARC</a>
<p>
The WIRE command is used to add wires (tracks) to a drawing. The wire
begins at the first point specified and runs to the second. Additional
points draw additional wire segments. Two mouse clicks at the same
position finish the wire and a new one can be started at the position
of the next mouse click.
<p>
Depending on the currently active wire bend, one or two wire segments will
be drawn between every two points. The wire bend defines the angle
between the segments and can be changed with the right mouse button (holding
the Shift key down while clicking the right mouse button reverses the direction
in which the bend styles are gone through, and the Ctrl key makes it toggle
between corresponding bend styles).
<p>
Pressing the center mouse button brings up a popup menu from which you
may select the layer into which the wire will be drawn.
<p>
The special keywords <tt>ROUND</tt> and <tt>FLAT</tt>, as well as the <i>curve</i>
parameter, can be used to draw an arc (see below).
<p>
Starting a WIRE with the Ctrl key pressed snaps the starting point
of the new wire to the coordinates of the closest existing wire. This
is especially useful if the existing wire is off grid. It also adjusts
the current width, layer and style to those of the existing wire.
If the current bend style is 7 ("Freehand"), the new wire will form a
smooth continuation of the existing wire.
<h2>Signal name</h2>
The <tt>signal_name</tt> parameter is intended mainly to be used in
script files that read in generated data. If a <tt>signal_name</tt>
is given, all subsequent wires will be added to that signal and no
automatic checks will be performed.<br>
<b>This feature should be used with great care because it could result
in short circuits, if a wire is placed in a way that it would connect
different signals. Please run a
<a href=#46>Design Rule Check</a> after using the WIRE command
with the <tt>signal_name</tt> parameter!</b>
<h2>Wire Width</h2>
Entering a number after activating the WIRE command changes the width
of the wire (in the present unit) which can be up to 0.51602 inch
(13.1 mm).
<p>
The wire width can be changed with the command
<pre>
CHANGE WIDTH width &#149;
</pre>
at any time.
<h2>Wire Style</h2>
Wires can have one of the following <i>styles</i>:
<ul>
<li>Continuous
<li>LongDash
<li>ShortDash
<li>DashDot
</ul>
The wire style can be changed with the <a href=#36>CHANGE</a> command.
<p>
Note that the DRC and Autorouter will always treat wires as "Continuous",
even if their style is different. Wire styles are mainly for electrical
and mechanical drawings and should not be used on signal layers. It is
an explicit DRC error to use a non-continuous wire as part of a signal
that is connected to any pad.
<h2>Signals in Top, Bottom, and Route Layers</h2>
Wires (tracks) in the layers Top, Bottom, and ROUTE2...15
are treated as signals. If you draw a wire in either of these layers
starting from an existing signal, then all of the segments of this wire
belong to that signal (only if the center of the wire is placed exactly onto
the center of the existing wire or pad). If you finish this drawing operation with a
wire segment connected to a different signal, then EAGLE will ask
you if you want to connect the two signals.
<p>
Note that EAGLE treats each wire segment as a single object
(e.g. when deleting a wire).
<p>
When the WIRE command is active the center mouse button
can be used to change the layer on which the wire is drawn.
<p>
Do not use the WIRE command for nets, buses, and airwires.
See <a href=#69>NET</a>,
<a href=#35>BUS</a> and
<a href=#94>SIGNAL</a>.
<h2>Drawing Arcs</h2>
Wires and arcs are basically the same objects, so you can draw an arc either by
using the <a href=#30>ARC</a> command, or by adding the necessary parameters
to the WIRE command. To make a wire an arc it needs either the <i>curve</i> parameter, which
defines the "curvature" of the arc, or the <i>@radius</i> parameter, which defines
the radius of the arc (note the <tt>'@'</tt>, which is necessary to be able to tell
apart <i>curve</i> and <i>radius</i>).
<p>
The valid range for <i>curve</i> is <tt>-360</tt>..<tt>+360</tt>, and its value means what
part of a full circle the arc consists of. A value of <tt>90</tt>, for instance,
would result in a <tt>90&deg;</tt> arc, while <tt>180</tt> would give you a semicircle.
The maximum value of <tt>360</tt> can only be reached theoretically, since this would
mean that the arc consists of a full circle, which, because the start and end points
have to lie on the circle, would have to have an infinitely large diameter. Positive
values for <i>curve</i> mean that the arc is drawn in a mathematically positive sense
(i.e. counterclockwise). If <i>curve</i> is <tt>0</tt>, the arc is a straight line
("no curvature"), which is actually a wire. Note that in order to distinguish the
<i>curve</i> parameter from the <i>width</i> parameter, it always has to be given with
a sign (<tt>'+'</tt> or <tt>'-'</tt>), even if it is a positive value.<br>
<p>
As an example, the command
<pre>
WIRE (0 0) +180 (0 10);
</pre>
would draw a semicircle from the point (0 0) to (0 10), in counterclockwise
direction.
<p>
If a <i>radius</i> is given, the arc will have that radius. Just like the <i>curve</i>
parameter, <i>radius</i> also must have a sign in order to determine the arcs
orientation.
For example, the command
<pre>
WIRE (0 0) @+100 (0 200);
</pre>
would draw a semicircle from the point (0 0) to (0 200) (with a radius of 100),
in counterclockwise direction. Note that if the end point is more than twice the
radius away from the start point, a straight line will be drawn.
<p>
The arc radius can also be defined by placing the wire end point with the <tt>Ctrl</tt>
key pressed (typically at the center of the circle on which the arc shall lie).
In that case the point is not taken as an actual end point, but is rather
used to set the radius of an arc. You can then move the cursor around and place an
arc with the given radius (the right mouse button together with <tt>Ctrl</tt> will
toggle the arc's orientation). If you move the cursor more than twice the radius
away from the start point, a straight line will be drawn.
<p>
In order to be able to draw any arc with the WIRE command (which is especially important
for generated script files), the keywords <tt>ROUND</tt> and <tt>FLAT</tt> are also
allowed in the WIRE command. Note, though, that these apply only to actual arcs
(straight wires always have round endings). By default, arcs created with the WIRE
command have round endings.
<a name=107>
<h1>WRITE</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Saves the current drawing or library.
<dt>
<b>Syntax</b>
<dd>
<tt>WRITE;</tt><br>
<tt>WRITE name</tt><br>
<tt>WRITE @name</tt>
</dl>
The WRITE command is used to save a drawing or library. If 'name'
is entered, EAGLE will save the file under the new name.
<p>
The file name may also be entered with a pathname if it is to
be saved in another directory. If no pathname is given, the file is
saved in the
<a href=#14>project directory</a>.
<p>
If the new name is preceded with a <tt>@</tt>, the name of the loaded
drawing will also be changed accordingly. The corresponding board/schematic
will then also be saved automatically under this name and the UNDO buffer
will be cleared.
<p>
If WRITE is selected from the menu, a popup window will appear asking
for the name to use (current drawing name is default). This name may
be edited and accepted by clicking the OK button. Pressing the ESCAPE
key or clicking the CANCEL button cancels the WRITE command.
<p>
To assure consistency for
<a href=#341>Forward&amp;Back Annotation</a>
between board and schematic drawings, the WRITE
command has the following additional functionality:
<ul>
<li>when a board/schematic is saved under the same name, the
corresponding schematic/board is also saved if it has been modified
<li>when a board/schematic is saved under a different name, the user
will be asked whether he also wants to save the schematic/board
under that different name
<li>saving a drawing under a different name does not clear the "modified" flag
</ul>
<a name=108>
<h1>Generating Output</h1>
<ul>
<li><a href=#109>Printing</a>
<li><a href=#113>CAM Processor</a>
<li><a href=#130>Outlines data</a>
</ul>
<a name=109>
<h1>Printing</h1>
The parameters for printing to the system printer can be modified through
the following three dialogs:
<ul>
<li><a href=#110>Printing a Drawing</a>
<li><a href=#111>Printing a Text</a>
<li><a href=#112>Printer Page Setup</a>
</ul>
<p>
<b>See also</b> <a href=#79>PRINT</a>
<a name=110>
<h1>Printing a Drawing</h1>
If you enter the <a href=#79>PRINT</a> command without a
terminating <tt>';'</tt>, or select <b>Print</b> from the
<a href=#13>context menu</a> of a drawing's icon in the
<a href=#12>Control Panel</a>, you will be presented a dialog
with the following options:
<h2>Paper</h2>
Selects which paper format to print on.
<h2>Orientation</h2>
Selects the paper orientation.
<h2>Preview</h2>
Turns the print preview on or off.
<h2>Mirror</h2>
Mirrors the output.
<h2>Rotate</h2>
Rotates the output by 90&deg;.
<h2>Upside down</h2>
Rotates the drawing by 180&deg;. Together with <b>Rotate</b> the drawing is rotated by a total of 270&deg;.
<h2>Black</h2>
Ignores the color settings of the layers and prints everything in black.
<h2>Solid</h2>
Ignores the fill style settings of the layers and prints everything in solid.
<h2>Scale factor</h2>
Scales the drawing by the given value.
<h2>Page limit</h2>
Defines the maximum number of pages you want the output to use.
In case the drawing does not fit on the given number of pages, the actual scale factor
will be reduced until it fits.
The default value of <tt>0</tt> means no limit.
<h2>All</h2>
All sheets of the schematic will be printed
(this is the default when selecting <b>Print</b> from the
<a href=#13>context menu</a> of a schematic drawing's icon).
<h2>From...to</h2>
Only the given range of sheets will be printed.
<h2>This</h2>
Only the sheet that is currently being edited will be printed
(this is the default when using the <a href=#79>PRINT</a> command
from a schematic editor window).
<h2>Printer...</h2>
Invokes the system printer dialog, which enables you to choose which printer
to use and to set printer specific parameters.
<h2>PDF...</h2>
Creates a PDF (Portable Document Format) file with the given print settings.
<p>
The remaining options are used for the <a href=#112>page setup</a>.
<a name=111>
<h1>Printing a Text</h1>
If you select <b>Print</b> from the
<a href=#13>context menu</a> of a text file's icon in the
<a href=#12>Control Panel</a>, or from the <b>File</b>
menu of the <a href=#26>Text Editor</a>, you will be presented
a dialog with the following options:
<h2>Wrap long lines</h2>
Enables wrapping lines that are too long to fit on the page width.
<h2>Printer...</h2>
Invokes the system printer dialog, which enables you to choose which printer
to use and to set printer specific parameters.
<h2>PDF...</h2>
Creates a PDF (Portable Document Format) file with the given print settings.
<p>
The remaining options are used for the <a href=#112>page setup</a>.
<a name=112>
<h1>Printer Page Setup</h1>
The Print dialog provides several options that are used to define how a drawing or text
shall be placed on the paper.
<h2>Border</h2>
Defines the left, top, right and bottom borders. The values are either in
millimeters or inches, depending on which unit results in fewer decimals.
<p>
The default border values are taken from the printer driver, and define
the maximum drawing area your particular printer can handle. You can enter
smaller values here, but your printer hardware may or may not be able to
print arbitrarily close to the paper edges.
<p>
After changing the printer new hardware minimums may apply and your
border values may be automatically enlarged as necessary to comply with
the new printer. Note that the values will not be decreased automatically
if a new printer would allow smaller values. To get the smallest possible
border values you can enter <tt>0</tt> in each field, which will then be
limited to the hardware minimum.
<h2>Calibrate</h2>
If you want to use your printer to produce production layout drawings,
you may have to calibrate your printer to achieve an exact 1:1
reproduction of your layout.
<p>
The value in the <b>X</b> field is the calibration factor to use
in the print head direction, while the value in the <b>Y</b> field
is used to calibrate the paper feed direction.
<p>
<b>IMPORTANT NOTE: When producing production layout drawings with
your printer, always check the final print result for correct measurements!</b>
<p>
The default values of <tt>1</tt> assume that the printer produces exact
measurements in both directions.
<h2>Aligment</h2>
Defines the vertical and horizontal alignment of the drawing on the paper.
<h2>Caption</h2>
Activates the printing of a caption line, containing the time and date
of the print as well as the file name.
<p>
If the drawing is mirrored, the word "mirrored" will appear in the caption,
and if the scale factor is not <tt>1.0</tt> it will be added as <b>f=...</b>
(the scale factor is given with 4 decimal digits, so even if <b>f=1.0000</b>
appears in the caption the scale factor will not be <i>exactly</i> <tt>1.0</tt>).
<a name=113>
<h1>CAM Processor</h1>
The CAM Processor allows you to output any combination of layers
to a device or file.
<p>
The following help topics lead you through the necessary steps from
selecting a data file to configuring the output device:
<ul>
<li><a href=#114>Select the data file</a>
<li><a href=#116>Select the output device type</a>
<li><a href=#127>Select the output file</a>
<li><a href=#129>Select the plot layers</a>
<li><a href=#117>Adjust the device parameters</a>
<li><a href=#128>Adjust the flag options</a>
</ul>
The CAM Processor allows you to combine several sets of parameter settings
to form a <a href=#115>CAM Processor Job</a>, which can be used to
produce a complete set of output files with a single click of a button.
<p>
<b>See also</b> <a href=#109>printing to the system printer</a>
<a name=114>
<h1>Main CAM Menu</h1>
The <i>Main CAM Menu</i> is where you select which file to process,
edit drill rack and aperture wheel files, and load or save job files.
<h2>File</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Open </td><td width=20><td>Board... open a board file for processing</td></tr>
<tr><td> </td><td width=20><td>Drill rack... open a drill rack file for editing</td></tr>
<tr><td> </td><td width=20><td>Wheel... open an aperture wheel file for editing</td></tr>
<tr><td> </td><td width=20><td>Job... switch to an other job (or create a new one)</td></tr>
<tr><td>Save job... </td><td width=20><td>save the current job</td></tr>
<tr><td>Close </td><td width=20><td>close the CAM Processor window</td></tr>
<tr><td>Exit </td><td width=20><td>exit from the program</td></tr>
</table>
<h2>Layer</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Deselect all </td><td width=20><td>deselect all layers</td></tr>
<tr><td>Show selected </td><td width=20><td>show only the selected layers</td></tr>
<tr><td>Show all </td><td width=20><td>show all layers</td></tr>
</table>
<h2>Window</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Control Panel </td><td width=20><td>switch to the Control Panel</td></tr>
<tr><td>1 Schematic - ... </td><td width=20><td>switch to window number 1</td></tr>
<tr><td>2 Board - ... </td><td width=20><td>switch to window number 2</td></tr>
</table>
<h2>Help</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>General help </td><td width=20><td>opens a general help page</td></tr>
<tr><td>Contents </td><td width=20><td>opens the help table of contents</td></tr>
<tr><td>CAM Processor </td><td width=20><td>displays help for the CAM Processor</td></tr>
<tr><td>Job help </td><td width=20><td>displays help about the Job mechanism</td></tr>
<tr><td>Device help </td><td width=20><td>displays help about output devices</td></tr>
</table>
<a name=115>
<h1>CAM Processor Job</h1>
A CAM Processor <i>Job</i> consists of several <i>Sections</i>,
each of which defines a complete set of CAM Processor parameters
and layer selections.
<p>
A typical CAM Processor job could for example have two sections, one
that produces photoplotter data for the Top layer, and another that
produces the data for the bottom layer.
<h2>Section</h2>
The <i>Section</i> selector shows the currently active job section.
By pressing the button you can select any of the sections you have defined
previously with the <i>Add</i> button.
<h2>Prompt</h2>
If you enter a text in this field, the CAM Processor will prompt you with
this message before processing that particular job section. For example you
might want to change the paper in your pen plotter for each plot, so the
message could be "Please change paper!". Each job section can have its own
prompt message, and if there is no message the section will be processed
immediately.
<h2>Add</h2>
Click on the <i>Add</i> button to add a new section to the job.
You will be asked for the name of that new job section. The new job section
will be created with all parameters set to the values currently shown
in the menu.<br>
Please note that if you want to create a new job section, you should
<b>first add</b> that new section and <b>then modify</b> the
parameters. Otherwise, if you first modify the parameters of the current
section and then add a new section, you will be prompted to confirm whether
the modifications to the current section shall be saved or not.
<h2>Del</h2>
Use the <i>Del</i> button to delete the current job section.
You will be prompted to confirm whether you really want to delete that
section.
<h2>Process Section</h2>
The <i>Process Section</i> button processes the current job section, as
indicated in the <i>Section</i> selector.
<h2>Process Job</h2>
The <i>Process Job</i> button processes the entire job by processing
each section in turn, starting with the first section. What happens is
the same as if you would select every single section with the
<i>Section</i> selector and press the <i>Process Section</i> button for
each section - just a lot more convenient!
<a name=116>
<h1>Output Device</h1>
The <i>Output Device</i> defines the kind of output the CAM Processor
is to produce. You can select from various device types, like photo plotters,
drill stations etc.
<h2>Device</h2>
Clicking on the button of the Device selector
opens a list of all available output devices.
<h2>Scale</h2>
On devices that can scale the output you can enter a scaling factor in
this field. Values larger than <tt>1</tt> will produce an enlarged output,
values smaller than <tt>1</tt> will shrink the output.
<p>
You can limit the size of the output to a given number of pages by entering
a negative number in the Scale field. In that case the default scale
factor will be 1.0 and will be decreased until the drawing just fits on the
given number of pages. For example, entering "-2" into this field will
produce a drawing that does not exceed two pages. Please note that for this
mechanism to work you will have to make sure that the page width and height
is set according to your output device. This setting can be adjusted in the
Width and Height fields or by editing the file eagle.def.
<h2>File</h2>
You can either enter the name of the
<a href=#127>output file</a>
directly into this field, or click on the
File button
to open a dialog for the definition of the output file.<br>
If you want to derive the output filename from the input data file, you
can enter a partial filename (at least an extension, e.g. <tt>.gbr</tt>),
in which case the rest of the filename will be taken from the input data
filename.
<h2>Wheel</h2>
You can either enter the name of the
<a href=#118>aperture wheel file</a>
directly into this field, or click on the Wheel button
to open a file dialog to select from.<br>
If you want to derive the output filename from the input data file, you
can enter a partial filename (at least an extension, e.g. <tt>.whl</tt>),
in which case the rest of the filename will be taken from the input data
filename.
<h2>Rack</h2>
You can either enter the name of the
<a href=#121>drill rack file</a>
directly into this field, or click on the Rack button
to open a file dialog to select from.<br>
If you want to derive the output filename from the input data file, you
can enter a partial filename (at least an extension, e.g. <tt>.drl</tt>),
in which case the rest of the filename will be taken from the input data
filename.
Some drill devices (like EXCELLON, for instance) can automatically generate the
necessary drill definitions, in which case this field is not present.
<a name=117>
<h1>Device Parameters</h1>
Depending on the type of <a href=#116>output device</a>
you have selected, there are several device specific parameters that
allow you to adjust the output to your needs:
<ul>
<li><a href=#118>Aperture Wheel File</a>
<li><a href=#119>Aperture Emulation</a>
<li><a href=#120>Aperture Tolerances</a>
<li><a href=#121>Drill Rack File</a>
<li><a href=#122>Drill Tolerances</a>
<li><a href=#123>Offset</a>
<li><a href=#124>Page Size</a>
<li><a href=#125>Pen Data</a>
</ul>
<a name=118>
<h1>Aperture Wheel File</h1>
A photoplotter usually needs to know which <i>apertures</i> are
assigned to the codes used in the output file. These assignments
are defined in an <i>Aperture Wheel File</i>.
<h2>Examples</h2>
<pre>
D010 annulus 0.004 x 0.000
D010 round 0.004
D040 square 0.004
D054 thermal 0.090 x 0.060
D100 rectangle 0.060 x 0.075
D104 oval 0.030 x 0.090
D110 draw 0.004
</pre>
Note that the file may contain several apertures that share the same D-code,
as long as all of these have a type from draw, round or annulus, and have
the same size (in case of annulus the second size parameter must be 0 in such
a case). This can be used to map apertures that effectively result in the
same drawing to a common D-code.
<a name=119>
<h1>Aperture Emulation</h1>
If the item "Apertures" is selected, apertures not available are
emulated with smaller apertures. If this item is not selected,
no aperture emulation will be done at all.
<p>
"Annulus" and/or "Thermal" is to be selected if these aperture types
are to be emulated (only effective if "Apertures" is selected, too).
<p>
Please note that aperture emulation can cause very long plot times (costs!).
<a name=120>
<h1>Aperture Tolerances</h1>
If you enter tolerances for draw and/or flash apertures the CAM
Processor uses apertures within the tolerances, provided the aperture
with the exact value is not available.
<p>
Tolerances are entered in percent.
<p>
<b>Please be aware that your design rules might not be kept when allowing
tolerances!</b>
<a name=121>
<h1>Drill Rack File</h1>
If a drill station driver can't automatically generate the necessary drill
definitions, it needs to know which <i>drill diameters</i>
are assigned to the codes used in the output file. These assignments
are defined in a <i>Drill Rack File</i>.
<p>
This file can be generated with the help of a User Language Program called
drillcfg.ulp, that is stored in your EAGLE's ULP directory.
Use the <a href=#90>RUN</a> command to start it.
<h2>Example</h2>
<pre>
T01 0.010
T02 0.016
T03 0.032
T04 0.040
T05 0.050
T06 0.070
</pre>
<a name=122>
<h1>Drill Tolerances</h1>
If you enter tolerances for drills the CAM Processor uses drill
diameters within the tolerances, provided the drill with the exact
value is not available.
<p>
Tolerances are entered in percent.
<a name=123>
<h1>Offset</h1>
Offset in x and y direction (inch, decimal number).
<p>
Can be used to position the origin of plotters at the lower left corner.
<a name=124>
<h1>Printable Area</h1>
<h2>Height</h2>
Printable area in <tt>Y</tt> direction (inch).
<h2>Width</h2>
Printable area in <tt>X</tt> direction (inch).
<p>
Please note that the CAM Processor divides a drawing into several
parts if the rectangle which includes all objects of the file
(even the ones not printed) doesn't fit into the printable area.
<a name=125>
<h1>Pen Data</h1>
<h2>Diameter</h2>
Pen diameter in mm. Is used for the calculation of lines
when areas have to be filled.
<h2>Velocity</h2>
Pen velocity in cm/s for pen plotters which can be adjusted
to different speeds.
<p>
The plotter default speed is selected with the value 0.
<a name=126>
<h1>Defining Your Own Device Driver</h1>
The drivers for output devices are defined in the text file eagle.def.
There you find details on how to define your own driver. It is
advisable to copy the whole section of an existing driver of the same
device category and to edit the parameters which are different.
<p>
Please use a <a href=#26>text editor</a> which doesn't
place control characters into the file.
<a name=127>
<h1>Output File</h1>
The <i>Output File</i> contains the data produced by the CAM Processor.
<p>
The following file names are commonly used:
<pre>
-------------------------------------------------------
File Layers Meaning
-------------------------------------------------------
*.cmp Top, Via, Pad Component side
*.ly2 Route2, Via, Pad Inner signal layer
*.ly3 Route3, Via, Pad Inner signal layer
*.ly4 $User1 Inner supply layer
... ...
*.sol Bot, Via, Pad Solder side
*.plc tPl, Dim, tName, Silkscreen comp. side
*.pls bPl, Dim, bName, Silkscreen solder side
*.stc tStop Solder stop mask comp. side
*.sts bStop Solder stop mask sold. side
*.drd Drills, Holes Drill data for NC drill st.
-------------------------------------------------------
</pre>
<h2>Placeholders</h2>
The output file name can either be entered directly, or can be dynamically
composed using <i>placeholders</i>. A placeholder consists of a percentage
character (<tt>'%'</tt>) followed by a letter. The following
placeholders are defined:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>%D{xxx}</tt></td><td width=20><td>a string that is inserted only into the data file name</td></tr>
<tr><td><tt>%E</tt> </td><td width=20><td>the loaded file's extension (without the <tt>'.'</tt>)</td></tr>
<tr><td><tt>%H</tt> </td><td width=20><td>the user's <a href=#14>home directory</a></td></tr>
<tr><td><tt>%I{xxx}</tt></td><td width=20><td>a string that is inserted only into the info file name</td></tr>
<tr><td><tt>%L</tt> </td><td width=20><td>the layer range for blind&amp;buried vias (see below)</td></tr>
<tr><td><tt>%N</tt> </td><td width=20><td>the loaded file's name (without path and extension)</td></tr>
<tr><td><tt>%P</tt> </td><td width=20><td>the loaded file's directory path (without file name)</td></tr>
<tr><td><tt>%%</tt> </td><td width=20><td>the character <tt>'%'</tt></td></tr>
</table>
<p>
For example, the output file definition
<p>
<tt>%N.cmp%I{.info}</tt>
<p>
would create <tt><i>boardname</i>.cmp</tt> for the data file and <tt><i>boardname</i>.cmp.info</tt>
for the info file (in case the selected output device generates an info file).
<h2>Drill data with blind&amp;buried vias</h2>
If the board contains blind or buried vias, the CAM
Processor generates a separate drill file for each via length that is
actually used in the board. The file names are built by adding the number
of the start and end layer to the base file name, as in
<pre>
<i>boardname</i>.drl.0104
</pre>
which would be the drill file for the layer stack 1-4. If you want to have
the layer numbers at a different position, you can use the placeholder <tt>%L</tt>,
as in
<pre>
%N.%L.drl
</pre>
which would result in
<pre>
<i>boardname</i>.0104.drl
</pre>
The drill info file name is always generated without layer numbers, and
any '.' before the <tt>%L</tt> will be dropped.
Any previously existing files that would match the given drill file name
pattern, but would not result from the current job, will be deleted before
generating any new files. There will be one drill info file per job, which
contains (amoung other information) a list of all generated drill data files.
<a name=128>
<h1>Flag Options</h1>
<h2>Mirror</h2>
Mirror output. This option normally causes negative
coordinates, therefore it should be used only if "pos. Coord." is
selected, too.
<h2>Rotate</h2>
Rotate drawing by 90 degrees. This option normally causes
negative coordinates, therefore it should be used only if "pos.
Coord." is selected, too.
<h2>Upside down</h2>
Rotate the drawing by 180 degrees. Together with Rotate, the
drawing is rotated by a total of 270 degrees. This option normally causes
negative coordinates, therefore it should be used only if "pos.
Coord." is selected, too.
<h2>pos. Coord</h2>
Offsets the output so that negative coordinates are
eliminated and the drawing is referenced to the origin of the output device.
This is advisable for devices which generate error messages if
negative coordinates are detected.
<h2>Quickplot</h2>
Draft output which shows only the outlines of objects (subject to availability
on the selected output device).
<h2>Optimize</h2>
Activates the optimization of the drawing sequence for plotters.
<h2>Fill pads</h2>
Pads will be filled. This function can be properly executed only with
generic devices, like PostScript.<br>
If this option is not selected, the drill holes of pads will be visible
on the output.
<a name=129>
<h1>Layers and Colors</h1>
Select the layer combination by clicking the check boxes in the
<i>Layer</i> list.
<p>
If you have selected an
<a href=#116>output device</a>
that supports colors, you can enter the color number
in the <i>Color</i> field of each layer.
<p>
The following layers and
<a href=#127>output file names</a>
are commonly used to create the output:
<pre>
-------------------------------------------------------
File Layers Meaning
-------------------------------------------------------
*.cmp Top, Via, Pad Component side
*.ly2 Route2, Via, Pad Inner signal layer
*.ly3 Route3, Via, Pad Inner signal layer
*.ly4 $User1 Inner supply layer
... ...
*.sol Bot, Via, Pad Solder side
*.plc tPl, Dim, tName, Silkscreen comp. side
*.pls bPl, Dim, bName, Silkscreen solder side
*.stc tStop Solder stop mask comp. side
*.sts bStop Solder stop mask sold. side
*.drd Drills, Holes Drill data for NC drill st.
-------------------------------------------------------
</pre>
<a name=130>
<h1>Outlines data</h1>
EAGLE can produce outlines data which can be used for milling prototype boards.
<p>
The User Language Program <i>outlines.ulp</i> implements the entire process
necessary to do this. The following is a detailed description of what exactly has to
be done to produce outlines data with EAGLE.
<h2>Preparing the board</h2>
Outlines data is produced by defining a <a href=#77>POLYGON</a>
in the layer for which the outlines shall be calculated.
This polygon must have the following properties:
<ul>
<li>its name must be _OUTLINES_
<li>it must be the <b>only</b> object in the signal named _OUTLINES_
<li>its <i>Rank</i> must be <tt>'6'</tt>
<li>its <i>Width</i> must be the same as the diameter of the milling tool
<li>it must be large enough to cover the entire board area
</ul>
If a polygon with these properties is present in your board, the
<a href=#81>RATSNEST</a> command will calculate it in such
a way that its <i>contours</i> correspond to the lines that have to be drawn by
the milling tool to isolate the various signals from each other.
The <i>fillings</i> of the calculated polygon define what has to be milled out
if you want to completely remove all superfluous copper areas.
<h2>Extracting the data</h2>
The outlines data can be extracted from the board through a
<a href=#138>User Language Program</a>. The <i>outlines.ulp</i>
program that comes with EAGLE implements this entire process. If you want to
write your own ULP you can use <i>outlines.ulp</i> as a starting point.
See the help page for <a href=#199>UL_POLYGON</a> for details
about how to retrieve the outlines data from a polygon object.
<h2>Milling tool diameter</h2>
The diameter of the milling tool (and thus the <i>Width</i> of the polygon) must
be small enough to fit between any two different signals in order to be able to
isolate them from each other.<br>
<b>Make sure you run a <a href=#46>Design Rule Check</a> (DRC) with
all <i>Clearance</i> values for different signals set to at least the diameter
of your milling tool!</b>
<p>
Non-zero values for the Isolate parameter can be used when working sequentially
with different milling tool diameters in order to avoid areas that have already
been milled.
<h2>Cleaning up</h2>
Make sure that you always delete the _OUTLINES_ polygon after generating the
outlines data. Leaving this polygon in your drawing will cause short circuits
since this special polygon does not adhere to the <a href=#133>Design Rules</a>!
<a name=131>
<h1>Autorouter</h1>
The integrated Autorouter can be started from a board window with the
<a href=#33>AUTO</a> command.
<p>
The Autorouter is also used as "Follow-me" router in the
<a href=#89>ROUTE</a> command.
<p>
Please check your <a href=#345>license</a>
to see whether you have access to the Autorouter module.
<a name=132>
<h1>Design Checks</h1>
There are two integrated commands that allow you to check your design:
<ul>
<li>Electrical Rule Check (<a href=#48>ERC</a>)
<li>Design Rule Check (<a href=#46>DRC</a>)
</ul>
The ERC is performed in a schematic window, and checks the design for
electrical consistency.
<p>
The DRC is performed in a board window, and checks the design for overlaps,
distance violations etc.
<a name=133>
<h1>Design Rules</h1>
<i>Design Rules</i> define all the parameters that the board layout has to follow.
<p>
The <a href=#46>Design Rule Check</a> checks the board against these rules
and reports any violations.
<p>
The Design Rules of a board can be modified through the Design Rules dialog, which
appears if the <a href=#46>DRC</a> command is selected without a terminating
<tt>';'</tt>.
<p>
Newly created boards take their design rules from the file 'default.dru',
which is searched for in the first directory listed in the "Options/Directories/Design rules" path.
If no such file is present, the program's builtin default values apply.
<p>
<b>Note</b> regarding the values for <b>Clearance</b> and <b>Distance</b>: since the internal
resolution of the coordinates is 1/10000mm, the DRC can only reliably report errors that
are larger than 1/10000mm.
<h2>File</h2>
The <i>File</i> tab shows a description of the current set of Design Rules and
allows you to <i>change</i> that description (this is strongly recommended if you define
your own Design Rules). There are also buttons to <i>load</i> a different set of Design
Rules from a disk file and to <i>save</i> the current Design Rules to disk.<br>
Note that the Design Rules are stored within the board file, so they will be in effect
if the board file is sent to a board house for production. The "Load..." and "Save as..."
buttons are merely for copying a board's Design Rules to and from disk.
<p>
If the Design Rules have been modified, the name in the dialog's title will have
trailing asterisk (<tt>'*'</tt>) to mark the Design Rules as modified. This mark
will be removed once the Design Rules are explicitly written to disk, or a new set
of Design Rules is loaded.
<h2>Layers</h2>
The <i>Layers</i> tab defines which signal layers the board actually uses, how thick
the copper and isolation layers are, and what kinds of vias can be placed
(note that this applies only to actual <i>vias</i>; so even if no via from layer 1 to
16 has been defined in the layer setup, <i>pads</i> will always be allowed).
<p>
The layer setup is defined by the string in the "Setup" field. This string consists of
a sequence of layer numbers, separated by one of the characters <tt>'*'</tt> or
<tt>'+'</tt>, where <tt>'*'</tt> stands for <i>core</i> material (also known as <i>FR4</i>
or something similar) and <tt>'+'</tt> stands for <i>prepreg</i> (or any other kind of
isolation material). The actual <i>core</i> and <i>prepreg</i> sequence has no meaning
to EAGLE other than varying the color in the layer display at the top left corner
of this tab (the actual multilayer setup always needs to be worked out with the
board manufacturer). The vias are defined by enclosing a sequence of layers with <tt>(...)</tt>.
So the setup string
<pre>
(1*16)
</pre>
would mean a two layer board, using layers 1 and 16 and vias going through the
entire board (this is also the default value).<br>
When building a multilayer board the setup could be something like
<pre>
((1*2)+(15*16))
</pre>
which is a four layer board with layer pairs 1/2 and 15/16 built on core material
and vias drilled through them, and finally the two layer pairs pressed together
with prepreg between them, and vias drilled all the way through the entire board.<br>
Besides vias that go trough an entire layer stack (which are commonly referred to
as <i>buried</i> vias in case they have no connection to the Top and Bottom layer)
there can also be vias that are not drilled all the way through a layer stack, but
rather end at a layer inside that stack. Such vias are known as <i>blind</i> vias
and are defined in the "Setup" string by enclosing a sequence of layers with
<tt>[t:...:b]</tt>, where <i>t</i> and <i>b</i> are the layers up to which that via
will go from the top or bottom side, respectively. A possible setup with <i>blind</i>
vias could be
<pre>
[2:1+((2*3)+(14*15))+16:15]
</pre>
which is basically the previous example, with two additional outer layers that are
connected to the next inner layers by <i>blind</i> vias. It is also
possible to have only one of the <i>t</i> or <i>b</i> parameters, so for instance
<pre>
[2:1+((2*3)+(15*16))]
</pre>
would also be a valid setup. Finally, <i>blind</i> vias are not limited to starting
at the Top or Bottom layer, but may also be used in inner layer stacks, as in
<pre>
[2:1+[3:2+(3*4)+5:4]+16:5]
</pre>
A <i>blind</i> via from layer <i>a</i> to layer <i>b</i> also implements all possible
<i>blind</i> vias from layer <i>a</i> to all layers between layers <i>a</i> and <i>b</i>, so
<pre>
[3:1+2+(3*16)]
</pre>
would allow <i>blind</i> vias from layer 1 to 2 as well as from 1 to 3.
<h2>Clearance</h2>
The <i>Clearance</i> tab defines the various minimum clearance values between objects
in signal layers. These are usually absolute minimum values that are defined by the
production process used and should be obtained from your board manufacturer.<br>
The actual minimum clearance between objects that belong to different signals will
also be influenced by the <a href=#38>net classes</a> the two signals belong to.
<p>
Note that a polygon in the special signal named _OUTLINES_ will be used to generate
<a href=#130>outlines data</a> and as such will <b>not</b> adhere to these
clearance values.
<h2>Distance</h2>
The <i>Distance</i> tab defines the minimum distance between objects in signal layers
and the board dimensions, as well as that between any two drill holes.
Note that only signals that are actually connected to at least one pad or
smd are checked against the board dimensions. This allows edge markers to be drawn
in the signal layer without generating DRC errors.
<p>
For compatibility with version 3.5x the following applies:
If the minimum distance between copper and dimension is set to <tt>0</tt>
objects in the Dimension layer will not be taken into account when calculating
polygons (except for Holes, which are always taken into account). This also disables
the distance check between copper and dimension objects.
<h2>Sizes</h2>
The <i>Sizes</i> tab defines the minimum width of any objects in signal layers and
the minimum drill diameter. These are usually absolute minimum values that are defined by the
production process used and should be obtained from your board manufacturer.<br>
The actual minimum width of signal wires and drill diameter of vias will
also be influenced by the Net Class the signal belongs to.
<h2>Restring</h2>
The <i>Restring</i> tab defines the width of the copper ring that has to remain after the
pad or via has been drilled. Values are defined in percent of the drill diameter and
there can be an absolute minimum and maximum limit. Restrings for pads can be different
for the top, bottom and inner layers, while for vias they can be different for the
outer and inner layers.<br>
If the actual diameter of a pad (as defined in the library) or a via would result in a
larger restring, that value will be used in the outer layers. Pads in library packages
can have their diameter set to 0, so that the restring will be derived entirely
from the drill diameter.
<h2>Shapes</h2>
The <i>Shapes</i> tab defines the actual shapes for smds and pads.<br>
Smds are normally defined as rectangles in the library (with a "roundness" of 0),
but if your design requires rounded smds you can specify the roundness factor here.<br>
Pads are normally defined as octagons in the library (long octagons where this makes
sense), and you can use the combo boxes to specify whether you want to have
pads with the same shapes as defined in the library, or always square, round or
octagonal. This can be set independently for the top and bottom layer.<br>
If the "first" pad of a package has been marked as such in the library
it will get the shape as defined in the third combo box (either round, square or
octagonal, or no special shape).<br>
The Elongation parameters define the appearance of pads with shape Long or Offset.
<h2>Supply</h2>
The <i>Supply</i> tab defines the dimensions of Thermal and Annulus symbols used in
supply layers.<br>
Please note that the actual shape of supply symbols may be different when generating
output for photoplotters that use specific thermal/annulus apertures!
See also the notes about "Supply Layers" in the <a href=#61>LAYER</a> command.
<h2>Masks</h2>
The <i>Masks</i> tab defines the dimensions of solder stop and cream masks. They are
given in percent of the smaller dimension of smds, pads and vias and can have an
absolute minimum and maximum value.<br>
Solder stop masks are generated for smds, pads and those vias that have a drill diameter
that exceeds the given Limit parameter.<br>
Cream masks are generated for smds only.
<h2>Misc</h2>
The <i>Misc</i> tab allows you to turn on a grid and angle check.
<p>
<a name=134>
<h1>Cross-references</h1>
There are various methods that can be used to create cross-references
in EAGLE schematic drawings. The following sections describe each of them.
<ul>
<li><a href=#135>Cross-reference labels</a>
<li><a href=#136>Part cross-references</a>
<li><a href=#137>Contact cross-references</a>
</ul>
<a name=135>
<h1>Cross-reference labels</h1>
A plain label can be used to make the name of a net visible in a schematic.
If a label has the <i>xref</i> property activated, its behavior is changed
so that it becomes a <i>cross-reference label</i>.
<p>
Cross-reference labels are typically placed at the right or left border of
a schematic sheet, and indicate the next (or previous) sheet a particular net
is used on. See the <a href=#60>LABEL</a> command for a detailed
description of how this works.
<a name=136>
<h1>Part cross-references</h1>
Electrical schematics often use electro-mechanical relays, consisting of a
coil and one or more contact symbols. If the coil and contacts are distributed
over various schematic sheets, it is useful to have each contact indicate
which sheet its coil is on. This can be achieved by giving the coil gate in
the device set an add level of <i>Must</i> (see the <a href=#29>ADD</a>
command) and placing the text variable <tt>'&gt;XREF'</tt> somewhere in the
contacts' symbols (see the <a href=#99>TEXT</a> command).
<p>
When actually displayed, the <tt>'&gt;XREF'</tt> text variable will be replaced
with the sheet number, frame column and row (according to the
<a href=#92>part cross-reference format</a>) of the <i>Must</i>
gate of this device.
<p>
See <a href=#137>Contact cross-references</a> on how
to display the contact locations on the coil's sheet.
<a name=137>
<h1>Contact cross-references</h1>
On a multi-sheet electrical schematic with electro-mechanical relays that
have their coils and contacts distributed over various sheets, it is useful
to be able to see which sheets the individual contacts of a relay are on.
EAGLE can automatically display this <i>contact cross-reference</i> for each
relay coil if the following conditions are met.
<p>
The contact symbols need to contain the <tt>'&gt;XREF'</tt> text variable
in order to generate <a href=#136>part cross-references</a>.
<p>
The gate symbols shall be drawn in a way that the pins extend up and down,
and that the origin is at the center of the symbol.
<p>
The first contact gate in the device set drawing shall be placed at an x-coordinate
of 0, and its y-coordinate shall be high enough to make sure its lower pin is in the
positive area, typically at 100mil. The rest of the contact gates shall be placed
to the right of the first one, with their origins at the same y-coordinate as the
first one. The coil gate can be placed at an arbitrary location.
<p>
In the schematic drawing the contact cross-reference will be shown at the same
x-coordinate as the coil instance, and right below the y-coordinate defined
by the text variable <tt>'&gt;CONTACT_XREF'</tt>. This text variable can be
defined either in a drawing frame symbol or directly on the sheet. If it is
present in both, the one in the sheet is taken. The actual text will not be visible
in the schematic sheet.
<p>
The graphical representation of the contact cross-reference consists of all the
gates that have an <tt>'&gt;XREF'</tt> text variable (except for the first <i>Must</i>
gate, which is the coil and typically doesn't have this variable). The gates are
rotated by 90 degrees and are shown from top to bottom at the same offsets
as they have been drawn from left to right in the device set. Their sheet numbers and
frame locations are displayed to the right of each gate that is actually used.
Any other texts that have been defined in the symbol drawings will not be
displayed when using these symbols for generating the contact cross-reference.
<p>
Note that the contact cross-reference can't be selected with the mouse. If you
want to move it, move the coil instance and the contact cross-reference will
automatically follow it.
The contact cross-reference may get out of sync in case contact gates are
invoked, moved, deleted or swapped, or if the <tt>'&gt;CONTACT_XREF'</tt> text
variable is modified. This will automatically be updated at the next window refresh.
<a name=138>
<h1>User Language</h1>
The EAGLE User Language can be used to access the EAGLE data structures
and to create a wide variety of output files.
<p>
To use this feature you have to
<a href=#139>write a User Language Program (ULP)</a>,
and then <a href=#140>execute</a> it.
<p>
The following sections describe the EAGLE User Language in detail:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><a href=#141>Syntax</a> </td><td width=20><td>lists the rules a ULP file has to follow</td></tr>
<tr><td><a href=#164>Data Types</a> </td><td width=20><td>defines the basic data types</td></tr>
<tr><td><a href=#171>Object Types</a> </td><td width=20><td>defines the EAGLE objects</td></tr>
<tr><td><a href=#210>Definitions</a> </td><td width=20><td>shows how to write a definition</td></tr>
<tr><td><a href=#214>Operators</a> </td><td width=20><td>lists the valid operators</td></tr>
<tr><td><a href=#221>Expressions</a> </td><td width=20><td>shows how to write expressions</td></tr>
<tr><td><a href=#228>Statements</a> </td><td width=20><td>defines the valid statements</td></tr>
<tr><td><a href=#240>Builtins</a> </td><td width=20><td>lists the builtin constants, functions etc.</td></tr>
<tr><td><a href=#302>Dialogs</a> </td><td width=20><td>shows how to implement a graphical frontent to a ULP</td></tr>
</table>
<a name=139>
<h1>Writing a ULP</h1>
A User Language Program is a plain text file which is written in a C-like
<a href=#141>syntax</a>.
User Language Programs use the extension <tt>.ulp</tt>.
You can create a ULP file with any text editor (provided it does
not insert any additional control characters into the file) or you can
use the <a href=#26>builtin text editor</a>.
<p>
A User Language Program consists of two major items,
<a href=#210>definitions</a> and
<a href=#228>statements</a>.
<p>
<a href=#210>Definitions</a> are used to define constants,
variables and functions to be used by <a href=#228>statements</a>.
<p>
A simple ULP could look like this:
<pre>
#usage "Add the characters in the word 'Hello'\n"
"Usage: RUN sample.ulp"
// Definitions:
string hello = "Hello";
int count(string s)
{
int c = 0;
for (int i = 0; s[i]; ++i)
c += s[i];
return c;
}
// Statements:
output("sample") {
printf("Count is: %d\n", count(hello));
}
</pre>
If the <tt><a href=#147>#usage</a></tt> directive is present,
its value will be used in the <a href=#12>Control Panel</a> to display a description
of the program.
<p>
If the result of the ULP shall be a specific command that shall be executed in the
editor window, the <tt><a href=#260>exit()</a></tt> function can be
used to send that command to the editor window.
<a name=140>
<h1>Executing a ULP</h1>
User Language Programs are executed by the
<a href=#90>RUN</a> command from an editor window's command line.
<p>
A ULP can return information on whether it has run successfully or not.
You can use the <tt><a href=#260>exit()</a></tt> function to terminate
the program and set the return value.
<p>
A return value of <tt>0</tt> means the ULP has ended "normally" (i.e.
successfully), while any other value is considered as an abnormal
program termination.
<p>
The default return value of any ULP is <tt>0</tt>.
<p>
When the <a href=#90>RUN</a> command is executed as part of a
<a href=#91>script file</a>, the script is terminated if
the ULP has exited with a return value other than <tt>0</tt>.
<p>
A special variant of the <tt><a href=#260>exit()</a></tt> function can be
used to send a command to the editor window as a result of the ULP.
<a name=141>
<h1>Syntax</h1>
The basic building blocks of a User Language Program are
<ul>
<li><a href=#142>Whitespace</a>
<li><a href=#143>Comments</a>
<li><a href=#144>Directives</a>
<li><a href=#148>Keywords</a>
<li><a href=#149>Identifiers</a>
<li><a href=#150>Constants</a>
<li><a href=#156>Punctuators</a>
</ul>
All of these have to follow certain syntactical rules, which are
described in their respective sections.
<a name=142>
<h1>Whitespace</h1>
Before a User Language Program can be executed, it has to be read in from
a file. During this read in process, the file contents is <i>parsed</i>
into tokens and <i>whitespace</i>.
<p>
Any spaces (blanks), tabs, newline characters and
<a href=#143>comments</a> are considered <i>whitespace</i>
and are discarded.
<p>
The only place where ASCII characters representing <i>whitespace</i>
are not discarded is within <a href=#150>literal strings</a>,
like in
<pre>
string s = "Hello World";
</pre>
where the blank character between <tt>'o'</tt> and <tt>'W'</tt> remains part
of the string.
<p>
If the final newline character of a line is preceded by a backslash
(<tt>\</tt>), the backslash and newline character are both discarded,
and the two lines are treated as one line:
<pre>
"Hello \
World"
</pre>
is parsed as <tt>"Hello World"</tt>
<a name=143>
<h1>Comments</h1>
When writing a User Language Program it is good practice to add some
descriptive text, giving the reader an idea about what this particular
ULP does. You might also want to add your name (and, if available, your
email address) to the ULP file, so that other people who use your program
could contact you in case they have a problem or would like to suggest
an improvement.
<p>
There are two ways to define a comment. The first one uses the syntax
<pre>
/* some comment text */
</pre>
which marks any characters between (and including) the opening
<tt>/*</tt> and the closing <tt>*/</tt> as comment. Such comments may expand over
more than one lines, as in
<pre>
/* This is a
multi line comment
*/
</pre>
but they do not nest. The first <tt>*/</tt> that follows any <tt>/*</tt>
will end the comment.
<p>
The second way to define a comment uses the syntax
<pre>
int i; // some comment text
</pre>
which marks any characters after (and including) the <tt>//</tt> and up
to (but not including) the newline character at the end of the line as
comment.
<a name=144>
<h1>Directives</h1>
The following <i>directives</i> are available:
<pre>
<a href=#145>#include</a>
<a href=#146>#require</a>
<a href=#147>#usage</a>
</pre>
<a name=145>
<h1>#include</h1>
A User Language Program can reuse code in other ULP files through the <tt>#include</tt>
directive. The syntax is
<pre>
#include "<i>filename</i>"
</pre>
The file <tt>filename</tt> is first looked for in the same directory as
the current source file (that is the file that contains the <tt>#include</tt>
directive). If it is not found there, it is searched for in
the directories contained in the ULP directory path.
<p>
The maximum include depth is 10.
<p>
Each <tt>#include</tt> directive is processed only <b>once</b>. This makes sure
that there are no multiple definitions of the same variables or functions, which
would cause errors.
<h2>Portability note</h2>
<table><tr><td valign="top"><img src="platforms-win.png"></td><td valign="middle">
If <i>filename</i> contains a directory path, it is best to always use the
<b>forward slash</b> as directory separator (even under Windows!). Windows drive
letters should be avoided. This way a User Language Program will run on all
platforms.
</td></tr></table>
<a name=146>
<h1>#require</h1>
Over time it may happen that newer versions of EAGLE implement new or modified
User Language features, which can cause error messages when such a ULP is run
from an older version of EAGLE. In order to give the user a dedicated message
that this ULP requires at least a certain version of EAGLE, a ULP can contain
the <tt>#require</tt> directive. The syntax is
<pre>
#require <i>version</i>
</pre>
The <i>version</i> must be given as a <a href=#153>real constant</a>
of the form
<pre>
V.RRrr
</pre>
where <tt>V</tt> is the version number, <tt>RR</tt> is the release number
and <tt>rr</tt> is the (optional) revision number (both padded with leading
zeroes if they are less than 10). For example, if a ULP
requires at least EAGLE version 4.11r06 (which is the beta version that first
implemented the <tt>#require</tt> directive), it could use
<pre>
#require 4.1106
</pre>
The proper directive for version 5.1.2 would be
<pre>
#require 5.0102
</pre>
<a name=147>
<h1>#usage</h1>
Every User Language Program should contain information about its function, how
to use it and maybe who wrote it.<br>
The directive
<pre>
#usage <i>text</i> [, <i>text</i>...]
</pre>
implements a standard way to make this information available.
<p>
If the <tt>#usage</tt> directive is present,
its <tt>text</tt> (which has to be a <a href=#154>string constant</a>)
will be used in the <a href=#12>Control Panel</a> to display a description
of the program.
<p>
In case the ULP needs to use this information in, for example, a
<a href=#306>dlgMessageBox()</a>, the <tt>text</tt> is available
to the program through the <a href=#241>builtin constant</a>
<tt>usage</tt>.
<p>
Only the <tt>#usage</tt> directive of the main program file (that is the one
started with the <a href=#90>RUN</a> command) will take effect.
Therefore pure <a href=#145>include</a> files can (and should!)
also have <tt>#usage</tt> directives of their own.
<p>
It is best to have the <tt>#usage</tt> directive at the beginning of the file,
so that the Control Panel doesn't have to parse all the rest of the text when
looking for the information to display.
<p>
If the usage information shall be made available in several langauges, the
texts of the individual languages have to be separated by commas.
Each of these texts has to start with the two letter code of the respective
language (as delivered by the <a href=#261>language()</a> function),
followed by a colon and any number of blanks. If no suitable text is found for
the language used on the actual system, the first given text will be used (this
one should generally be English in order to make the program accessible to the
largest number of users).
<h2>Example</h2>
<pre>
#usage "en: A sample ULP\n"
"Implements an example that shows how to use the EAGLE User Language\n"
"Usage: RUN sample.ulp\n"
"Author: john@home.org",
"de: Beispiel eines ULPs\n"
"Implementiert ein Beispiel das zeigt, wie man die EAGLE User Language benutzt\n"
"Aufruf: RUN sample.ulp\n"
"Author: john@home.org"
</pre>
<a name=148>
<h1>Keywords</h1>
The following <i>keywords</i> are reserved for special purposes
and must not be used as normal identifier names:
<pre>
<a href=#232>break</a>
<a href=#238>case</a>
<a href=#165>char</a>
<a href=#233>continue</a>
<a href=#238>default</a>
<a href=#234>do</a>
<a href=#236>else</a>
<a href=#211>enum</a>
<a href=#235>for</a>
<a href=#236>if</a>
<a href=#166>int</a>
<a href=#212>numeric</a>
<a href=#167>real</a>
<a href=#237>return</a>
<a href=#168>string</a>
<a href=#238>switch</a>
<a href=#164>void</a>
<a href=#239>while</a>
</pre>
In addition, the names of
<a href=#240>builtins</a> and
<a href=#171>object types</a>
are also reserved and must not be used as identifier names.
<a name=149>
<h1>Identifiers</h1>
An <i>identifier</i> is a name that is used to introduce a user defined
<a href=#211>constant</a>,
<a href=#212>variable</a> or
<a href=#213>function</a>.
<p>
Identifiers consist of a sequence of letters (<tt>a b c</tt>..., <tt>A B C</tt>...),
digits (<tt>1 2 3</tt>...) and underscores (<tt>_</tt>). The first character
of an identifier <b>must</b> be a letter or an underscore.
<p>
Identifiers are case-sensitive, which means that
<pre>
int Number, number;
</pre>
would define two <b>different</b> integer variables.
<p>
The maximum length of an identifier is 100 characters, and all of these
are significant.
<a name=150>
<h1>Constants</h1>
Constants are literal data items written into a User Language Program.
According to the different <a href=#164>data types</a>,
there are also different types of constants.
<ul>
<li><a href=#151>Character constants</a>
<li><a href=#152>Integer constants</a>
<li><a href=#153>Real constants</a>
<li><a href=#154>String constants</a>
</ul>
<a name=151>
<h1>Character Constants</h1>
A <i>character constant</i> consists of a single character or
an <a href=#155>escape sequence</a> enclosed in
single quotes, like
<pre>
'a'
'='
'\n'
</pre>
The type of a character constant is
<tt><a href=#165>char</a></tt>.
<a name=152>
<h1>Integer Constants</h1>
Depending on the first (and possibly the second) character, an
<i>integer constant</i> is assumed to be expressed in different
base values:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>first</td> <td width=20><td>second</td> <td width=20><td>constant interpreted as</td></tr>
<tr><td><tt>0</tt></td> <td width=20><td><tt>1-7</tt></td> <td width=20><td>octal (base 8)</td></tr>
<tr><td><tt>0</tt></td> <td width=20><td><tt>x,X</tt></td> <td width=20><td>hexadecimal (base 16)</td></tr>
<tr><td><tt>1-9</tt></td> <td width=20><td> </td> <td width=20><td>decimal (base 10)</td></tr>
</table>
<p>
The type of an integer constant is
<tt><a href=#166>int</a></tt>.
<h2>Examples</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>16</tt> </td><td width=20><td>decimal</td></tr>
<tr><td><tt>020</tt> </td><td width=20><td>octal</td></tr>
<tr><td><tt>0x10</tt> </td><td width=20><td>hexadecimal</td></tr>
</table>
<a name=153>
<h1>Real Constants</h1>
A <i>real constant</i> follows the general pattern
<pre>
[-]<i>int</i>.<i>frac</i>[e|E[&plusmn;]<i>exp</i>]
</pre>
which stands for
<ul>
<li>optional sign
<li>decimal integer
<li>decimal point
<li>decimal fraction
<li><tt>e</tt> or <tt>E</tt> and a signed integer exponent
</ul>
You can omit either the decimal integer or the decimal fraction
(but not both). You can omit either the decimal point or the
letter <tt>e</tt> or <tt>E</tt> and the signed integer exponent
(but not both).
<p>
The type of an real constant is
<tt><a href=#167>real</a></tt>.
<h2>Examples</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Constant </td><td width=20><td>Value</td></tr>
<tr><td><tt>23.45e6</tt> </td><td width=20><td>23.45 x 10^6</td></tr>
<tr><td><tt>.0</tt> </td><td width=20><td>0.0</td></tr>
<tr><td><tt>0.</tt> </td><td width=20><td>0.0</td></tr>
<tr><td><tt>1.</tt> </td><td width=20><td>1.0</td></tr>
<tr><td><tt>-1.23</tt> </td><td width=20><td>-1.23</td></tr>
<tr><td><tt>2e-5</tt> </td><td width=20><td>2.0 x 10^-5</td></tr>
<tr><td><tt>3E+10</tt> </td><td width=20><td>3.0 x 10^10</td></tr>
<tr><td><tt>.09E34</tt> </td><td width=20><td>0.09 x 10^34</td></tr>
</table>
<a name=154>
<h1>String Constants</h1>
A <i>string constant</i> consists of a sequence of characters or
<a href=#155>escape sequences</a> enclosed in
double quotes, like
<pre>
"Hello world\n"
</pre>
The type of a string constant is
<tt><a href=#168>string</a></tt>.
<p>
String constants can be of any length (provided there is enough free memory
available).
<p>
String constants can be concatenated by simply writing them next to each other
to form larger strings:
<pre>
string s = "Hello" " world\n";
</pre>
It is also possible to extend a string constant over more than one line
by escaping the newline character with a backslash (<tt>\</tt>):
<pre>
string s = "Hello \
world\n";
</pre>
<a name=155>
<h1>Escape Sequences</h1>
An <i>escape sequence</i> consists of a backslash (<tt>\</tt>), followed
by one or more special characters:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Sequence </td><td width=20><td>Value</td></tr>
<tr><td><tt>\a</tt> </td><td width=20><td>audible bell</td></tr>
<tr><td><tt>\b</tt> </td><td width=20><td>backspace</td></tr>
<tr><td><tt>\f</tt> </td><td width=20><td>form feed</td></tr>
<tr><td><tt>\n</tt> </td><td width=20><td>new line</td></tr>
<tr><td><tt>\r</tt> </td><td width=20><td>carriage return</td></tr>
<tr><td><tt>\t</tt> </td><td width=20><td>horizontal tab</td></tr>
<tr><td><tt>\v</tt> </td><td width=20><td>vertical tab</td></tr>
<tr><td><tt>\\</tt> </td><td width=20><td>backslash</td></tr>
<tr><td><tt>\'</tt> </td><td width=20><td>single quote</td></tr>
<tr><td><tt>\"</tt> </td><td width=20><td>double quote</td></tr>
<tr><td><tt>\O</tt> </td><td width=20><td><tt>O</tt> = up to 3 octal digits</td></tr>
<tr><td><tt>\xH</tt> </td><td width=20><td><tt>H</tt> = up to 2 hex digits</td></tr>
</table>
<p>
Any character following the initial backslash that is not mentioned in
this list will be treated as that character (without the backslash).
<p>
Escape sequences can be used in
<a href=#151>character constants</a> and
<a href=#154>string constants</a>.
<h2>Examples</h2>
<pre>
'\n'
"A tab\tinside a text\n"
"Ring the bell\a\n"
</pre>
<a name=156>
<h1>Punctuators</h1>
The <i>punctuators</i> used in a User Language Program are
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>[]</tt> </td><td width=20><td><a href=#157>Brackets</a></td></tr>
<tr><td><tt>()</tt> </td><td width=20><td><a href=#158>Parentheses</a></td></tr>
<tr><td><tt>{}</tt> </td><td width=20><td><a href=#159>Braces</a></td></tr>
<tr><td><tt>,</tt> </td><td width=20><td><a href=#160>Comma</a></td></tr>
<tr><td><tt>;</tt> </td><td width=20><td><a href=#161>Semicolon</a></td></tr>
<tr><td><tt>:</tt> </td><td width=20><td><a href=#162>Colon</a></td></tr>
<tr><td><tt>=</tt> </td><td width=20><td><a href=#163>Equal sign</a></td></tr>
</table>
<p>
Other special characters are used as <a href=#214>operators</a>
in a ULP.
<a name=157>
<h1>Brackets</h1>
<i>Brackets</i> are used in array definitions
<pre>
int ai[];
</pre>
in array subscripts
<pre>
n = ai[2];
</pre>
and in string subscripts to access the individual characters of a string
<pre>
string s = "Hello world";
char c = s[2];
</pre>
<a name=158>
<h1>Parentheses</h1>
<i>Parentheses</i> group <a href=#221>expressions</a>
(possibly altering normal
<a href=#214>operator</a> precedence), isolate conditional
expressions, and indicate
<a href=#227>function calls</a> and function parameters:
<pre>
d = c * (a + b);
if (d == z) ++x;
func();
void func2(int n) { ... }
</pre>
<a name=159>
<h1>Braces</h1>
<i>Braces</i> indicate the start and end of a compound statement:
<pre>
if (d == z) {
++x;
func();
}
</pre>
and are also used to group the values of an array initializer:
<pre>
int ai[] = { 1, 2, 3 };
</pre>
<a name=160>
<h1>Comma</h1>
The <i>comma</i> separates the elements of a function argument list
or the parameters of a function call:
<pre>
int func(int n, real r, string s) { ... }
int i = func(1, 3.14, "abc");
</pre>
It also delimits the values of an array initializer:
<pre>
int ai[] = { 1, 2, 3 };
</pre>
and it separates the elements of a variable definition:
<pre>
int i, j, k;
</pre>
<a name=161>
<h1>Semicolon</h1>
The <i>semicolon</i> terminates a <a href=#228>statement</a>,
as in
<pre>
i = a + b;
</pre>
and it also delimits the init, test and increment expressions of a
<a href=#235>for</a> statement:
<pre>
for (int n = 0; n &lt; 3; ++n) {
func(n);
}
</pre>
<a name=162>
<h1>Colon</h1>
The <i>colon</i> indicates the end of a label in a
<a href=#238>switch</a> statement:
<pre>
switch (c) {
case 'a': printf("It was an 'a'\n"); break;
case 'b': printf("It was a 'b'\n"); break;
default: printf("none of them\n");
}
</pre>
<a name=163>
<h1>Equal Sign</h1>
The <i>equal sign</i> separates variable definitions from initialization
lists:
<pre>
int i = 10;
char c[] = { 'a', 'b', 'c' };
</pre>
It is also used as an <a href=#219>assignment operator</a>.
<a name=164>
<h1>Data Types</h1>
A User Language Program can define variables of different types, representing
the different kinds of information available in the EAGLE data structures.
<p>
The four basic data types are
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt><a href=#165>char</a></tt> </td><td width=20><td>for single characters</td></tr>
<tr><td><tt><a href=#166>int</a></tt> </td><td width=20><td>for integral values</td></tr>
<tr><td><tt><a href=#167>real</a></tt> </td><td width=20><td>for floating point values</td></tr>
<tr><td><tt><a href=#168>string</a></tt> </td><td width=20><td>for textual information</td></tr>
</table>
<p>
Besides these basic data types there are also high level
<a href=#171>Object Types</a>, which
represent the data structures stored in the EAGLE data files.
<p>
The special data type <tt>void</tt> is used only as a return type of a
<a href=#213>function</a>, indicating that this
function does <b>not</b> return any value.
<a name=165>
<h1>char</h1>
The data type <tt>char</tt> is used to store single characters, like the
letters of the alphabet, or small unsigned numbers.
<p>
A variable of type <tt>char</tt> has a size of 8 bit (one byte), and can
store any value in the range <tt>0..255</tt>.
<p>
<b>See also</b> <a href=#214>Operators</a>,
<a href=#151>Character Constants</a>
<a name=166>
<h1>int</h1>
The data type <tt>int</tt> is used to store signed integral values, like the
coordinates of an object.
<p>
A variable of type <tt>int</tt> has a size of 32 bit (four byte), and can
store any value in the range <tt>-2147483648..2147483647</tt>.
<p>
<b>See also</b> <a href=#152>Integer Constants</a>
<a name=167>
<h1>real</h1>
The data type <tt>real</tt> is used to store signed floating point values, like
the grid distance.
<p>
A variable of type <tt>real</tt> has a size of 64 bit (eight byte), and can
store any value in the range <tt>&plusmn;2.2e-308..&plusmn;1.7e+308</tt> with a
precision of 15 digits.
<p>
<b>See also</b> <a href=#153>Real Constants</a>
<a name=168>
<h1>string</h1>
The data type <tt>string</tt> is used to store textual information,
like the name of a part or net.
<p>
A variable of type <tt>string</tt> is not limited in it's size (provided
there is enough memory available).
<p>
Variables of type <tt>string</tt> are defined without an explicit
<i>size</i>. They grow automatically as necessary during program
execution.
<p>
The elements of a <tt>string</tt> variable are of type
<tt><a href=#165>char</a></tt> and
can be accessed individually by using <tt>[index]</tt>.
The first character of a <tt>string</tt> has the index <tt>0</tt>:
<pre>
string s = "Layout";
printf("Third char is: %c\n", s[2]);
</pre>
This would print the character <tt>'y'</tt>. Note that <tt>s[2]</tt> returns
the <b>third</b> character of <tt>s</tt>!
<p>
<b>See also</b> <a href=#214>Operators</a>,
<a href=#243>Builtin Functions</a>,
<a href=#154>String Constants</a>
<h2>Implementation details</h2>
The data type <tt>string</tt> is actually implemented like native C-type
zero terminated strings (i.e. <tt>char[]</tt>). Looking at the following
variable definition
<pre>
string s = "abcde";
</pre>
<tt>s[4]</tt> is the character <tt>'e'</tt>, and <tt>s[5]</tt> is the character
<tt>'\0'</tt>, or the integer value <tt>0x00</tt>.
This fact may be used to determine the end of a string without using the
<tt><a href=#274>strlen()</a></tt> function, as in
<pre>
for (int i = 0; s[i]; ++i) {
// do something with s[i]
}
</pre>
It is also perfectly ok to "cut off" part of a string by "punching" a zero
character into it:
<pre>
string s = "abcde";
s[3] = 0;
</pre>
This will result in <tt>s</tt> having the value <tt>"abc"</tt>.
Note that everything following the zero character will actually be gone,
and it won't come back by restoring the original character. The same applies
to any other operation that sets a character to 0, for instance --s[3].
<a name=169>
<h1>Type Conversions</h1>
The result type of an arithmetic
<a href=#221>expression</a>, such as <tt>a + b</tt>,
where <tt>a</tt> and <tt>b</tt> are different arithmetic types,
is equal to the "larger" of the two operand types.
<p>
Arithmetic types are
<tt><a href=#165>char</a></tt>,
<tt><a href=#166>int</a></tt> and
<tt><a href=#167>real</a></tt>
(in that order). So if, e.g. <tt>a</tt> is of type
<tt><a href=#166>int</a></tt>
and <tt>b</tt> is of type
<tt><a href=#167>real</a></tt>,
the result of the expression <tt>a + b</tt> would be
<tt><a href=#167>real</a></tt>.
<p>
<b>See also</b> <a href=#170>Typecast</a>
<a name=170>
<h1>Typecast</h1>
The result type of an arithmetic <a href=#221>expression</a>
can be explicitly converted to a different arithmetic type by applying a
<i>typecast</i> to it.
<p>
The general syntax of a typecast is
<pre>
type(expression)
</pre>
where <tt>type</tt> is one of
<tt><a href=#165>char</a></tt>,
<tt><a href=#166>int</a></tt> or
<tt><a href=#167>real</a></tt>,
and <tt>expression</tt> is any arithmetic
<a href=#221>expression</a>.
<p>
When typecasting a <tt><a href=#167>real</a></tt> expression to
<tt><a href=#166>int</a></tt>, the fractional part of the value
is truncated!
<p>
<b>See also</b> <a href=#169>Type Conversions</a>
<a name=171>
<h1>Object Types</h1>
The EAGLE data structures are stored in three binary file types:
<ul>
<li>Library (*.lbr)
<li>Schematic (*.sch)
<li>Board (*.brd)
</ul>
These data files contain a hierarchy of objects.
In a User Language Program you can access these hierarchies through their
respective builtin access statements:
<pre>
<a href=#296>library</a>(L) { ... }
<a href=#299>schematic</a>(S) { ... }
<a href=#294>board</a>(B) { ... }
</pre>
These access statements set up a context within which you can access all of the
objects contained in the library, schematic or board.
<p>
The properties of these objects can be accessed through <i>members</i>.
<p>
There are two kinds of members:
<ul>
<li>Data members
<li>Loop members
</ul>
<b>Data members</b> immediately return the requested data from an object.
For example, in
<pre>
board(B) {
printf("%s\n", B.name);
}
</pre>
the data member <i>name</i> of the board object <i>B</i> returns
the board's name.<br>
Data members can also return other objects, as in
<pre>
board(B) {
printf("%f\n", B.grid.size);
}
</pre>
where the board's <i>grid</i> data member returns a grid object,
of which the <i>size</i> data member then returns the grid's size.
<p>
<b>Loop members</b> are used to access multiple objects of the same
kind, which are contained in a higher level object:
<pre>
board(B) {
B.elements(E) {
printf("%-8s %-8s\n", E.name, E.value);
}
}
</pre>
This example uses the board's <i>elements()</i> loop member function
to set up a loop through all of the board's elements. The block following
the <tt>B.elements(E)</tt> statement is executed in turn for each element,
and the current element can be referenced inside the block through the name
<tt>E</tt>.
<p>
Loop members process objects in alpha-numerical order, provided they
have a name.
<p>
A loop member function creates a variable of the type necessary to hold
the requested objects. You are free to use any valid name for such a
variable, so the above example might also be written as
<pre>
board(MyBoard) {
MyBoard.elements(TheCurrentElement) {
printf("%-8s %-8s\n", TheCurrentElement.name, TheCurrentElement.value);
}
}
</pre>
and would do the exact same thing. The scope of the variable created by a
loop member function is limited to the statement (or block) immediately
following the loop function call.
<p>
Object hierarchy of a Library:
<pre>
<a href=#192>LIBRARY</a>
<a href=#186>GRID</a>
<a href=#191>LAYER</a>
<a href=#182>DEVICESET</a>
<a href=#181>DEVICE</a>
<a href=#185>GATE</a>
<a href=#194>PACKAGE</a>
<a href=#179>CONTACT</a>
<a href=#195>PAD</a>
<a href=#205>SMD</a>
<a href=#177>CIRCLE</a>
<a href=#187>HOLE</a>
<a href=#200>RECTANGLE</a>
<a href=#184>FRAME</a>
<a href=#207>TEXT</a>
<a href=#209>WIRE</a>
<a href=#199>POLYGON</a>
<a href=#209>WIRE</a>
<a href=#206>SYMBOL</a>
<a href=#197>PIN</a>
<a href=#177>CIRCLE</a>
<a href=#200>RECTANGLE</a>
<a href=#184>FRAME</a>
<a href=#207>TEXT</a>
<a href=#209>WIRE</a>
<a href=#199>POLYGON</a>
<a href=#209>WIRE</a>
</pre>
Object hierarchy of a Schematic:
<pre>
<a href=#201>SCHEMATIC</a>
<a href=#186>GRID</a>
<a href=#191>LAYER</a>
<a href=#192>LIBRARY</a>
<a href=#203>SHEET</a>
<a href=#177>CIRCLE</a>
<a href=#200>RECTANGLE</a>
<a href=#184>FRAME</a>
<a href=#207>TEXT</a>
<a href=#209>WIRE</a>
<a href=#199>POLYGON</a>
<a href=#209>WIRE</a>
<a href=#196>PART</a>
<a href=#188>INSTANCE</a>
<a href=#174>ATTRIBUTE</a>
<a href=#176>BUS</a>
<a href=#202>SEGMENT</a>
<a href=#190>LABEL</a>
<a href=#207>TEXT</a>
<a href=#209>WIRE</a>
<a href=#209>WIRE</a>
<a href=#193>NET</a>
<a href=#202>SEGMENT</a>
<a href=#189>JUNCTION</a>
<a href=#198>PINREF</a>
<a href=#207>TEXT</a>
<a href=#209>WIRE</a>
</pre>
Object hierarchy of a Board:
<pre>
<a href=#175>BOARD</a>
<a href=#186>GRID</a>
<a href=#191>LAYER</a>
<a href=#192>LIBRARY</a>
<a href=#177>CIRCLE</a>
<a href=#187>HOLE</a>
<a href=#200>RECTANGLE</a>
<a href=#184>FRAME</a>
<a href=#207>TEXT</a>
<a href=#209>WIRE</a>
<a href=#199>POLYGON</a>
<a href=#209>WIRE</a>
<a href=#183>ELEMENT</a>
<a href=#174>ATTRIBUTE</a>
<a href=#204>SIGNAL</a>
<a href=#180>CONTACTREF</a>
<a href=#199>POLYGON</a>
<a href=#209>WIRE</a>
<a href=#208>VIA</a>
<a href=#209>WIRE</a>
</pre>
<a name=172>
<h1>UL_ARC</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>angle1</tt> </td><td width=20><td><a href=#167>real</a> (start angle, <tt>0.0</tt>...<tt>359.9</tt>)</td></tr>
<tr><td><tt>angle2</tt> </td><td width=20><td><a href=#167>real</a> (end angle, <tt>0.0</tt>...<tt>719.9</tt>)</td></tr>
<tr><td><tt>cap</tt> </td><td width=20><td><a href=#166>int</a> (<tt>CAP_...</tt>)</td></tr>
<tr><td><tt>layer</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>radius</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>width</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>x1, y1</tt> </td><td width=20><td><a href=#166>int</a> (starting point)</td></tr>
<tr><td><tt>x2, y2</tt> </td><td width=20><td><a href=#166>int</a> (end point)</td></tr>
<tr><td><tt>xc, yc</tt> </td><td width=20><td><a href=#166>int</a> (center point)</td></tr>
</table>
</dl>
<b>See also</b> <a href=#209>UL_WIRE</a>
<h2>Constants</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>CAP_FLAT</tt> </td><td width=20><td>flat arc ends</td></tr>
<tr><td><tt>CAP_ROUND</tt> </td><td width=20><td>round arc ends</td></tr>
</table>
<h2>Note</h2>
Start and end angles are defined mathematically positive (i.e. counterclockwise),
with <tt>angle1</tt> &lt; <tt>angle2</tt>.
In order to assure this condition, the start and end point of an UL_ARC may be exchanged
with respect to the UL_WIRE the arc has been derived from.
<h2>Example</h2>
<pre>
board(B) {
B.wires(W) {
if (W.arc)
printf("Arc: (%d %d), (%d %d), (%d %d)\n",
W.arc.x1, W.arc.y1, W.arc.x2, W.arc.y2, W.arc.xc, W.arc.yc);
}
}
</pre>
<a name=173>
<h1>UL_AREA</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>x1, y1</tt> </td><td width=20><td><a href=#166>int</a> (lower left corner)</td></tr>
<tr><td><tt>x2, y2</tt> </td><td width=20><td><a href=#166>int</a> (upper right corner)</td></tr>
</table>
</dl>
<b>See also</b> <a href=#175>UL_BOARD</a>,
<a href=#181>UL_DEVICE</a>,
<a href=#194>UL_PACKAGE</a>,
<a href=#203>UL_SHEET</a>,
<a href=#206>UL_SYMBOL</a>
<p>
A UL_AREA is an abstract object which gives information about the area
covered by an object. For a UL_DEVICE, UL_PACKAGE and UL_SYMBOL the area
is defined as the surrounding rectangle of the object definition in the
library, so even if e.g. a UL_PACKAGE is derived from a UL_ELEMENT, the
package's area will not reflect the elements offset within the board.
<h2>Example</h2>
<pre>
board(B) {
printf("Area: (%d %d), (%d %d)\n",
B.area.x1, B.area.y1, B.area.x2, B.area.y2);
}
</pre>
<a name=174>
<h1>UL_ATTRIBUTE</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>constant</tt> </td><td width=20><td><a href=#166>int</a> (0=variable, i.e. allows overwriting, 1=constant - see note)</td></tr>
<tr><td><tt>defaultvalue</tt> </td><td width=20><td><a href=#168>string</a> (see note)</td></tr>
<tr><td><tt>display</tt> </td><td width=20><td><a href=#166>int</a> (<tt>ATTRIBUTE_DISPLAY_FLAG_...</tt>)</td></tr>
<tr><td><tt>name</tt> </td><td width=20><td><a href=#168>string</a></td></tr>
<tr><td><tt>text</tt> </td><td width=20><td><a href=#207>UL_TEXT</a> (see note)</td></tr>
<tr><td><tt>value</tt> </td><td width=20><td><a href=#168>string</a></td></tr>
</table>
</dl>
<b>See also</b> <a href=#181>UL_DEVICE</a>,
<a href=#196>UL_PART</a>,
<a href=#188>UL_INSTANCE</a>,
<a href=#183>UL_ELEMENT</a>
<h2>Constants</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>ATTRIBUTE_DISPLAY_FLAG_OFF</tt> </td><td width=20><td>nothing is displayed</td></tr>
<tr><td><tt>ATTRIBUTE_DISPLAY_FLAG_VALUE</tt> </td><td width=20><td>value is displayed</td></tr>
<tr><td><tt>ATTRIBUTE_DISPLAY_FLAG_NAME</tt> </td><td width=20><td>name is displayed</td></tr>
</table>
<p>
A UL_ATTRIBUTE can be used to access the <i>attributes</i> that have been
defined in the library for a device, or assigned to a part in the schematic
or board.
<h2>Note</h2>
<tt>display</tt> contains a bitwise or'ed value consisting of <tt>ATTRIBUTE_DISPLAY_FLAG_...</tt>
and defines which parts of the attribute are actually drawn.
This value is only valid if <tt>display</tt> is used in a UL_INSTANCE or UL_ELEMENT
context.
<p>
In a UL_ELEMENT context <tt>constant</tt> only returns an actual value if
f/b annotation is active, otherwise it returns 0.
<p>
The <tt>defaultvalue</tt> member returns the value as defined in the library
(if different from the actual value, otherwise the same as <tt>value</tt>).
In a UL_ELEMENT context <tt>defaultvalue</tt> only returns an actual value if
f/b annotation is active, otherwise an empty string is returned.
<p>
The <tt>text</tt> member is only available in a UL_INSTANCE or UL_ELEMENT
context and returns a UL_TEXT object that contains all the text parameters.
The value of this text object is the string as it will be displayed according to
the UL_ATTRIBUTE's 'display' parameter. If called from a different context,
the data of the returned UL_TEXT object is undefined.
<p>
For global attributes only <tt>name</tt> and <tt>value</tt> are defined.
<h2>Example</h2>
<pre>
schematic(SCH) {
SCH.parts(P) {
P.attributes(A) {
printf("%s = %s\n", A.name, A.value);
}
}
}
schematic(SCH) {
SCH.attributes(A) { // global attributes
printf("%s = %s\n", A.name, A.value);
}
}
</pre>
<a name=175>
<h1>UL_BOARD</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>area</tt> </td><td width=20><td><a href=#173>UL_AREA</a></td></tr>
<tr><td><tt>grid</tt> </td><td width=20><td><a href=#186>UL_GRID</a></td></tr>
<tr><td><tt>name</tt> </td><td width=20><td><a href=#168>string</a> (see note)</td></tr>
</table>
<dt>
<b>Loop members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>attributes()</tt> </td><td width=20><td><a href=#174>UL_ATTRIBUTE</a> (see note)</td></tr>
<tr><td><tt>circles()</tt> </td><td width=20><td><a href=#177>UL_CIRCLE</a></td></tr>
<tr><td><tt>classes()</tt> </td><td width=20><td><a href=#178>UL_CLASS</a></td></tr>
<tr><td><tt>elements()</tt> </td><td width=20><td><a href=#183>UL_ELEMENT</a></td></tr>
<tr><td><tt>frames()</tt> </td><td width=20><td><a href=#184>UL_FRAME</a></td></tr>
<tr><td><tt>holes()</tt> </td><td width=20><td><a href=#187>UL_HOLE</a></td></tr>
<tr><td><tt>layers()</tt> </td><td width=20><td><a href=#191>UL_LAYER</a></td></tr>
<tr><td><tt>libraries()</tt> </td><td width=20><td><a href=#192>UL_LIBRARY</a></td></tr>
<tr><td><tt>polygons()</tt> </td><td width=20><td><a href=#199>UL_POLYGON</a></td></tr>
<tr><td><tt>rectangles()</tt> </td><td width=20><td><a href=#200>UL_RECTANGLE</a></td></tr>
<tr><td><tt>signals()</tt> </td><td width=20><td><a href=#204>UL_SIGNAL</a></td></tr>
<tr><td><tt>texts()</tt> </td><td width=20><td><a href=#207>UL_TEXT</a></td></tr>
<tr><td><tt>wires()</tt> </td><td width=20><td><a href=#209>UL_WIRE</a></td></tr>
</table>
</dl>
<b>See also</b> <a href=#192>UL_LIBRARY</a>,
<a href=#201>UL_SCHEMATIC</a>
<h2>Note</h2>
The <tt>name</tt> member returns the full file name, including the directory.
<p>
The <tt>attributes()</tt> loop member loops through the <i>global</i> attributes.
<h2>Example</h2>
<pre>
board(B) {
B.elements(E) printf("Element: %s\n", E.name);
B.signals(S) printf("Signal: %s\n", S.name);
}
</pre>
<a name=176>
<h1>UL_BUS</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>name</tt> </td><td width=20><td><a href=#168>string</a> (<tt>BUS_NAME_LENGTH</tt>)</td></tr>
</table>
<dt>
<b>Loop members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>segments()</tt> </td><td width=20><td><a href=#202>UL_SEGMENT</a></td></tr>
</table>
</dl>
<b>See also</b> <a href=#203>UL_SHEET</a>
<h2>Constants</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>BUS_NAME_LENGTH</tt> </td><td width=20><td>max. length of a bus name (obsolete - as from version 4 bus names can have any length)</td></tr>
</table>
<h2>Example</h2>
<pre>
schematic(SCH) {
SCH.sheets(SH) {
SH.busses(B) printf("Bus: %s\n", B.name);
}
}
</pre>
<a name=177>
<h1>UL_CIRCLE</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>layer</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>radius</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>width</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>x, y</tt> </td><td width=20><td><a href=#166>int</a> (center point)</td></tr>
</table>
</dl>
<b>See also</b> <a href=#175>UL_BOARD</a>,
<a href=#194>UL_PACKAGE</a>,
<a href=#203>UL_SHEET</a>,
<a href=#206>UL_SYMBOL</a>
<h2>Example</h2>
<pre>
board(B) {
B.circles(C) {
printf("Circle: (%d %d), r=%d, w=%d\n",
C.x, C.y, C.radius, C.width);
}
}
</pre>
<a name=178>
<h1>UL_CLASS</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>clearance[number]</tt></td><td width=20><td><a href=#166>int</a> (see note)</td></tr>
<tr><td><tt>drill</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>name</tt> </td><td width=20><td><a href=#168>string</a> (see note)</td></tr>
<tr><td><tt>number</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>width</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
</table>
</dl>
<b>See also</b> <a href=#133>Design Rules</a>,
<a href=#193>UL_NET</a>,
<a href=#204>UL_SIGNAL</a>,
<a href=#201>UL_SCHEMATIC</a>,
<a href=#175>UL_BOARD</a>
<h2>Note</h2>
The <tt>clearance</tt> member returns the clearance value between this net class
and the net class with the given number. If the number (and the square brackets) is
ommitted, the net class's own clearance value is returned. If a number is given,
it must be between 0 and the number of this net class.
<p>
If the <tt>name</tt> member returns an empty string, the net class is not defined
and therefore not in use by any signal or net.
<h2>Example</h2>
<pre>
board(B) {
B.signals(S) {
printf("%-10s %d %s\n", S.name, S.class.number, S.class.name);
}
}
</pre>
<a name=179>
<h1>UL_CONTACT</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>name</tt> </td><td width=20><td><a href=#168>string</a> (<tt>CONTACT_NAME_LENGTH</tt>)</td></tr>
<tr><td><tt>pad</tt> </td><td width=20><td><a href=#195>UL_PAD</a></td></tr>
<tr><td><tt>signal</tt> </td><td width=20><td><a href=#168>string</a></td></tr>
<tr><td><tt>smd</tt> </td><td width=20><td><a href=#205>UL_SMD</a></td></tr>
<tr><td><tt>x, y</tt> </td><td width=20><td><a href=#166>int</a> (center point, see note)</td></tr>
</table>
</dl>
<b>See also</b> <a href=#194>UL_PACKAGE</a>,
<a href=#195>UL_PAD</a>,
<a href=#205>UL_SMD</a>,
<a href=#180>UL_CONTACTREF</a>,
<a href=#198>UL_PINREF</a>
<h2>Constants</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>CONTACT_NAME_LENGTH</tt> </td><td width=20><td>max. recommended length of a contact name (used in formatted output only)</td></tr>
</table>
<h2>Note</h2>
The <tt>signal</tt> data member returns the signal this contact is connected to
(only available in a board context).
<p>
The coordinates (<tt>x, y</tt>) of the contact depend on the context in which it is called:
<ul>
<li>if the contact is derived from a UL_LIBRARY context, the coordinates of the contact will be the same as
defined in the package drawing
<li>in all other cases, they will have the actual values from the board
</ul>
<h2>Example</h2>
<pre>
library(L) {
L.packages(PAC) {
PAC.contacts(C) {
printf("Contact: '%s', (%d %d)\n",
C.name, C.x, C.y);
}
}
}
</pre>
<a name=180>
<h1>UL_CONTACTREF</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>contact</tt> </td><td width=20><td><a href=#179>UL_CONTACT</a></td></tr>
<tr><td><tt>element</tt> </td><td width=20><td><a href=#183>UL_ELEMENT</a></td></tr>
</table>
</dl>
<b>See also</b> <a href=#204>UL_SIGNAL</a>,
<a href=#198>UL_PINREF</a>
<h2>Example</h2>
<pre>
board(B) {
B.signals(S) {
printf("Signal '%s'\n", S.name);
S.contactrefs(C) {
printf("\t%s, %s\n", C.element.name, C.contact.name);
}
}
}
</pre>
<a name=181>
<h1>UL_DEVICE</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>area</tt> </td><td width=20><td><a href=#173>UL_AREA</a></td></tr>
<tr><td><tt>description</tt> </td><td width=20><td><a href=#168>string</a></td></tr>
<tr><td><tt>headline</tt> </td><td width=20><td><a href=#168>string</a></td></tr>
<tr><td><tt>library</tt> </td><td width=20><td><a href=#168>string</a></td></tr>
<tr><td><tt>name</tt> </td><td width=20><td><a href=#168>string</a> (<tt>DEVICE_NAME_LENGTH</tt>)</td></tr>
<tr><td><tt>package</tt> </td><td width=20><td><a href=#194>UL_PACKAGE</a> (see note)</td></tr>
<tr><td><tt>prefix</tt> </td><td width=20><td><a href=#168>string</a> (<tt>DEVICE_PREFIX_LENGTH</tt>)</td></tr>
<tr><td><tt>technologies</tt> </td><td width=20><td><a href=#168>string</a> (see note)</td></tr>
<tr><td><tt>value</tt> </td><td width=20><td><a href=#168>string</a> ("On" or "Off")</td></tr>
</table>
<dt>
<b>Loop members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>attributes()</tt> </td><td width=20><td><a href=#174>UL_ATTRIBUTE</a> (see note)</td></tr>
<tr><td><tt>gates()</tt> </td><td width=20><td><a href=#185>UL_GATE</a></td></tr>
</table>
</dl>
<b>See also</b> <a href=#182>UL_DEVICESET</a>,
<a href=#192>UL_LIBRARY</a>,
<a href=#196>UL_PART</a>
<h2>Constants</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>DEVICE_NAME_LENGTH</tt> </td><td width=20><td>max. recommended length of a device name (used in formatted output only)</td></tr>
<tr><td><tt>DEVICE_PREFIX_LENGTH</tt> </td><td width=20><td>max. recommended length of a device prefix (used in formatted output only)</td></tr>
</table>
<p>
All members of UL_DEVICE, except for <tt>name</tt> and <tt>technologies</tt>, return the
same values as the respective members of the UL_DEVICESET in which the UL_DEVICE has been
defined.
The <tt>name</tt> member returns the name of the package variant this device
has been created for using the <a href=#72>PACKAGE</a> command.
When using the <tt>description</tt> text keep in mind that it may contain newline characters (<tt>'\n'</tt>).
<h2>Note</h2>
The <tt>package</tt> data member returns the <a href=#194>package</a>
that has been assigned to the device through a <a href=#72>PACKAGE</a>
command. It can be used as a boolean function to check whether a package has been
assigned to a device (see example below).
<p>
The value returned by the <tt>technologies</tt> member depends on the context in which it is called:
<ul>
<li>if the device is derived from a UL_DEVICESET, <tt>technologies</tt> will return a
string containing all of the device's technologies, separated by blanks
<li>if the device is derived from a UL_PART, only the actual technology used by the part
will be returned.
</ul>
<p>
The <tt>attributes()</tt> loop member takes an additional parameter that specifies
for which technology the attributes shall be delivered (see the second example below).
<h2>Examples</h2>
<pre>
library(L) {
L.devicesets(S) {
S.devices(D) {
if (D.package)
printf("Device: %s, Package: %s\n", D.name, D.package.name);
D.gates(G) {
printf("\t%s\n", G.name);
}
}
}
}
</pre>
<pre>
library(L) {
L.devicesets(DS) {
DS.devices(D) {
string t[];
int n = strsplit(t, D.technologies, ' ');
for (int i = 0; i &lt; n; i++) {
D.attributes(A, t[i]) {
printf("%s = %s\n", A.name, A.value);
}
}
}
}
}
</pre>
<a name=182>
<h1>UL_DEVICESET</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>area</tt> </td><td width=20><td><a href=#173>UL_AREA</a></td></tr>
<tr><td><tt>description</tt> </td><td width=20><td><a href=#168>string</a></td></tr>
<tr><td><tt>headline</tt> </td><td width=20><td><a href=#168>string</a> (see note)</td></tr>
<tr><td><tt>library</tt> </td><td width=20><td><a href=#168>string</a></td></tr>
<tr><td><tt>name</tt> </td><td width=20><td><a href=#168>string</a> (<tt>DEVICE_NAME_LENGTH</tt>)</td></tr>
<tr><td><tt>prefix</tt> </td><td width=20><td><a href=#168>string</a> (<tt>DEVICE_PREFIX_LENGTH</tt>)</td></tr>
<tr><td><tt>value</tt> </td><td width=20><td><a href=#168>string</a> ("On" or "Off")</td></tr>
</table>
<dt>
<b>Loop members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>devices()</tt> </td><td width=20><td><a href=#181>UL_DEVICE</a></td></tr>
<tr><td><tt>gates()</tt> </td><td width=20><td><a href=#185>UL_GATE</a></td></tr>
</table>
</dl>
<b>See also</b> <a href=#181>UL_DEVICE</a>,
<a href=#192>UL_LIBRARY</a>,
<a href=#196>UL_PART</a>
<h2>Constants</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>DEVICE_NAME_LENGTH</tt> </td><td width=20><td>max. recommended length of a device name (used in formatted output only)</td></tr>
<tr><td><tt>DEVICE_PREFIX_LENGTH</tt> </td><td width=20><td>max. recommended length of a device prefix (used in formatted output only)</td></tr>
</table>
<h2>Note</h2>
The <tt>description</tt> member returns the complete descriptive text as defined with
the <a href=#44>DESCRIPTION</a> command, while the <tt>headline</tt>
member returns only the first line of the description, without any <a href=#339>HTML</a> tags.
When using the <tt>description</tt> text keep in mind that it may contain newline characters (<tt>'\n'</tt>).
<h2>Example</h2>
<pre>
library(L) {
L.devicesets(D) {
printf("Device set: %s, Description: %s\n", D.name, D.description);
D.gates(G) {
printf("\t%s\n", G.name);
}
}
}
</pre>
<a name=183>
<h1>UL_ELEMENT</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>angle</tt> </td><td width=20><td><a href=#167>real</a> (<tt>0.0</tt>...<tt>359.9</tt>)</td></tr>
<tr><td><tt>attribute[]</tt> </td><td width=20><td><a href=#168>string</a> (see note)</td></tr>
<tr><td><tt>column</tt> </td><td width=20><td><a href=#168>string</a> (see note)</td></tr>
<tr><td><tt>locked</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>mirror</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>name</tt> </td><td width=20><td><a href=#168>string</a> (<tt>ELEMENT_NAME_LENGTH</tt>)</td></tr>
<tr><td><tt>package</tt> </td><td width=20><td><a href=#194>UL_PACKAGE</a></td></tr>
<tr><td><tt>row</tt> </td><td width=20><td><a href=#168>string</a> (see note)</td></tr>
<tr><td><tt>smashed</tt> </td><td width=20><td><a href=#166>int</a> (see note)</td></tr>
<tr><td><tt>spin</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>value</tt> </td><td width=20><td><a href=#168>string</a> (<tt>ELEMENT_VALUE_LENGTH</tt>)</td></tr>
<tr><td><tt>x, y</tt> </td><td width=20><td><a href=#166>int</a> (origin point)</td></tr>
</table>
<dt>
<b>Loop members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>attributes()</tt> </td><td width=20><td><a href=#174>UL_ATTRIBUTE</a></td></tr>
<tr><td><tt>texts()</tt> </td><td width=20><td><a href=#207>UL_TEXT</a> (see note)</td></tr>
</table>
</dl>
<b>See also</b> <a href=#175>UL_BOARD</a>,
<a href=#180>UL_CONTACTREF</a>
<h2>Constants</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>ELEMENT_NAME_LENGTH</tt> </td><td width=20><td>max. recommended length of an element name (used in formatted output only)</td></tr>
<tr><td><tt>ELEMENT_VALUE_LENGTH</tt> </td><td width=20><td>max. recommended length of an element value (used in formatted output only)</td></tr>
</table>
<h2>Note</h2>
The <tt>attribute[]</tt> member can be used to query a UL_ELEMENT for the value of a given
attribute (see the second example below). The returned string is empty if there is no
attribute by the given name, or if this attribute is explicitly empty.
<p>
The <tt>texts()</tt> member only loops through those texts of the element that have been
detached using <a href=#95><b>SMASH</b></a>,
and through the visible texts of any attributes assigned to this element.
To process all texts of an element (e.g. when drawing it), you have to loop through the element's
own <tt>texts()</tt> member as well as the <tt>texts()</tt> member of the
element's <a href=#194>package</a>.
<p>
<tt>angle</tt> defines how many degrees the element is rotated counterclockwise
around its origin.
<p>
The <tt>column()</tt> and <tt>row()</tt> members return the column and row location within
the <a href=#184>frame</a> in the board drawing.
If there is no frame in the drawing, or the element is placed outside the frame, a <tt>'?'</tt>
(question mark) is returned.
<p>
The <tt>smashed</tt> member tells whether the element is smashed. This function can also
be used to find out whether there is a detached text parameter by giving the name of
that parameter in square brackets, as in <tt>smashed["VALUE"]</tt>. This is useful
in case you want to select such a text with the <a href=#67>MOVE</a> command
by doing <tt>MOVE R5&gt;VALUE</tt>. Valid parameter names are "NAME" and "VALUE", as
well as the names of any user defined <a href=#174>attributes</a>.
They are treated case insensitive, and they may be preceded by a <tt>'&gt;'</tt>
character.
<h2>Examples</h2>
<pre>
board(B) {
B.elements(E) {
printf("Element: %s, (%d %d), Package=%s\n",
E.name, E.x, E.y, E.package.name);
}
}
</pre>
<pre>
board(B) {
B.elements(E) {
if (E.attribute["REMARK"])
printf("%s: %s\n", E.name, E.attribute("REMARK"));
}
}
</pre>
<a name=184>
<h1>UL_FRAME</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>columns</tt> </td><td width=20><td><a href=#166>int</a> (<tt>-127</tt>...<tt>127</tt>)</td></tr>
<tr><td><tt>rows</tt> </td><td width=20><td><a href=#166>int</a> (<tt>-26</tt>...<tt>26</tt>)</td></tr>
<tr><td><tt>border</tt> </td><td width=20><td><a href=#166>int</a> (<tt>FRAME_BORDER_...</tt>)</td></tr>
<tr><td><tt>layer</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>x1, y1</tt> </td><td width=20><td><a href=#166>int</a> (lower left corner)</td></tr>
<tr><td><tt>x2, y2</tt> </td><td width=20><td><a href=#166>int</a> (upper right corner)</td></tr>
</table>
<dt>
<b>Loop members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>texts()</tt> </td><td width=20><td><a href=#207>UL_TEXT</a></td></tr>
<tr><td><tt>wires()</tt> </td><td width=20><td><a href=#209>UL_WIRE</a></td></tr>
</table>
</dl>
<b>See also</b> <a href=#175>UL_BOARD</a>,
<a href=#194>UL_PACKAGE</a>,
<a href=#203>UL_SHEET</a>,
<a href=#206>UL_SYMBOL</a>
<h2>Constants</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>FRAME_BORDER_BOTTOM</tt> </td><td width=20><td>bottom border is drawn</td></tr>
<tr><td><tt>FRAME_BORDER_RIGHT</tt> </td><td width=20><td>right border is drawn</td></tr>
<tr><td><tt>FRAME_BORDER_TOP</tt> </td><td width=20><td>top border is drawn</td></tr>
<tr><td><tt>FRAME_BORDER_LEFT</tt> </td><td width=20><td>left border is drawn</td></tr>
</table>
<h2>Note</h2>
<tt>border</tt> contains a bitwise or'ed value consisting of <tt>FRAME_BORDER_...</tt>
and defines which of the four borders are actually drawn.
<p>
The <tt>texts()</tt> and <tt>wires()</tt> loop members loop through all the
texts and wires the frame consists of.
<h2>Example</h2>
<pre>
board(B) {
B.frames(F) {
printf("Frame: (%d %d), (%d %d)\n",
F.x1, F.y1, F.x2, F.y2);
}
}
</pre>
<a name=185>
<h1>UL_GATE</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>addlevel</tt> </td><td width=20><td><a href=#166>int</a> (<tt>GATE_ADDLEVEL_...</tt>)</td></tr>
<tr><td><tt>name</tt> </td><td width=20><td><a href=#168>string</a> (<tt>GATE_NAME_LENGTH</tt>)</td></tr>
<tr><td><tt>swaplevel</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>symbol</tt> </td><td width=20><td><a href=#206>UL_SYMBOL</a></td></tr>
<tr><td><tt>x, y</tt> </td><td width=20><td><a href=#166>int</a> (origin point, see note)</td></tr>
</table>
</dl>
<b>See also</b> <a href=#181>UL_DEVICE</a>
<h2>Constants</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>GATE_ADDLEVEL_MUST</tt> </td><td width=20><td>must</td></tr>
<tr><td><tt>GATE_ADDLEVEL_CAN</tt> </td><td width=20><td>can</td></tr>
<tr><td><tt>GATE_ADDLEVEL_NEXT</tt> </td><td width=20><td>next</td></tr>
<tr><td><tt>GATE_ADDLEVEL_REQUEST</tt> </td><td width=20><td>request</td></tr>
<tr><td><tt>GATE_ADDLEVEL_ALWAYS</tt> </td><td width=20><td>always</td></tr>
</table>
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>GATE_NAME_LENGTH</tt> </td><td width=20><td>max. recommended length of a gate name (used in formatted output only)</td></tr>
</table>
<h2>Note</h2>
The coordinates of the origin point (x, y) are always those of the gate's position within
the device, even if the UL_GATE has been derived from a <a href=#188>UL_INSTANCE</a>.
<h2>Example</h2>
<pre>
library(L) {
L.devices(D) {
printf("Device: %s, Package: %s\n", D.name, D.package.name);
D.gates(G) {
printf("\t%s, swaplevel=%d, symbol=%s\n",
G.name, G.swaplevel, G.symbol.name);
}
}
}
</pre>
<a name=186>
<h1>UL_GRID</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>distance</tt> </td><td width=20><td><a href=#167>real</a></td></tr>
<tr><td><tt>dots</tt> </td><td width=20><td><a href=#166>int</a> (0=lines, 1=dots)</td></tr>
<tr><td><tt>multiple</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>on</tt> </td><td width=20><td><a href=#166>int</a> (0=off, 1=on)</td></tr>
<tr><td><tt>unit</tt> </td><td width=20><td><a href=#166>int</a> (<tt>GRID_UNIT_...</tt>)</td></tr>
<tr><td><tt>unitdist</tt> </td><td width=20><td><a href=#166>int</a> (<tt>GRID_UNIT_...</tt>)</td></tr>
</table>
</dl>
<b>See also</b> <a href=#175>UL_BOARD</a>,
<a href=#192>UL_LIBRARY</a>,
<a href=#201>UL_SCHEMATIC</a>,
<a href=#267>Unit Conversions</a>
<h2>Constants</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>GRID_UNIT_MIC</tt> </td><td width=20><td>microns</td></tr>
<tr><td><tt>GRID_UNIT_MM</tt> </td><td width=20><td>millimeter</td></tr>
<tr><td><tt>GRID_UNIT_MIL</tt> </td><td width=20><td>mil</td></tr>
<tr><td><tt>GRID_UNIT_INCH</tt> </td><td width=20><td>inch</td></tr>
</table>
<h2>Note</h2>
<tt>unitdist</tt> returns the grid unit that was set to define the actual grid size
(returned by <tt>distance</tt>), while <tt>unit</tt> returns the grid unit that is
used to display values or interpret user input.
<h2>Example</h2>
<pre>
board(B) {
printf("Gridsize=%f\n", B.grid.distance);
}
</pre>
<a name=187>
<h1>UL_HOLE</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>diameter[layer]</tt> </td><td width=20><td><a href=#166>int</a> (see note)</td></tr>
<tr><td><tt>drill</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>drillsymbol</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>x, y</tt> </td><td width=20><td><a href=#166>int</a> (center point)</td></tr>
</table>
</dl>
<b>See also</b> <a href=#175>UL_BOARD</a>,
<a href=#194>UL_PACKAGE</a>
<h2>Note</h2>
<tt>diameter[]</tt> is only defined vor layers <tt>LAYER_TSTOP</tt> and <tt>LAYER_BSTOP</tt>
and returns the diameter of the solder stop mask in the given layer.
<p>
<tt>drillsymbol</tt> returns the number of the drill symbol that has been assigned
to this drill diameter (see the manual for a list of defined drill symbols).
A value of <tt>0</tt> means that no symbol has been assigned to this drill diameter.
<h2>Example</h2>
<pre>
board(B) {
B.holes(H) {
printf("Hole: (%d %d), drill=%d\n",
H.x, H.y, H.drill);
}
}
</pre>
<a name=188>
<h1>UL_INSTANCE</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>angle</tt> </td><td width=20><td><a href=#167>real</a> (<tt>0</tt>, <tt>90</tt>, <tt>180</tt> and <tt>270</tt>)</td></tr>
<tr><td><tt>column</tt> </td><td width=20><td><a href=#168>string</a> (see note)</td></tr>
<tr><td><tt>gate</tt> </td><td width=20><td><a href=#185>UL_GATE</a></td></tr>
<tr><td><tt>mirror</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>name</tt> </td><td width=20><td><a href=#168>string</a> (<tt>INSTANCE_NAME_LENGTH</tt>)</td></tr>
<tr><td><tt>row</tt> </td><td width=20><td><a href=#168>string</a> (see note)</td></tr>
<tr><td><tt>sheet</tt> </td><td width=20><td><a href=#166>int</a> (0=unused, &gt;0=sheet number)</td></tr>
<tr><td><tt>smashed</tt> </td><td width=20><td><a href=#166>int</a> (see note)</td></tr>
<tr><td><tt>value</tt> </td><td width=20><td><a href=#168>string</a> (<tt>PART_VALUE_LENGTH</tt>)</td></tr>
<tr><td><tt>x, y</tt> </td><td width=20><td><a href=#166>int</a> (origin point)</td></tr>
</table>
<dt>
<b>Loop members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>attributes()</tt> </td><td width=20><td><a href=#174>UL_ATTRIBUTE</a> (see note)</td></tr>
<tr><td><tt>texts()</tt> </td><td width=20><td><a href=#207>UL_TEXT</a> (see note)</td></tr>
<tr><td><tt>xrefs()</tt> </td><td width=20><td><a href=#185>UL_GATE</a> (see note)</td></tr>
</table>
</dl>
<b>See also</b> <a href=#196>UL_PART</a>,
<a href=#198>UL_PINREF</a>
<h2>Constants</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>INSTANCE_NAME_LENGTH</tt> </td><td width=20><td>max. recommended length of an instance name (used in formatted output only)</td></tr>
<tr><td><tt>PART_VALUE_LENGTH</tt> </td><td width=20><td>max. recommended length of a part value (instances do not have a value of their own!)</td></tr>
</table>
<h2>Note</h2>
The <tt>attributes()</tt> member only loops through those attributes that have been
explicitly assigned to this instance (including <i>smashed</i> attributes).
<p>
The <tt>texts()</tt> member only loops through those texts of the instance that have been
detached using <a href=#95><b>SMASH</b></a>,
and through the visible texts of any attributes assigned to this instance.
To process all texts of an instance, you have to loop through the instance's
own <tt>texts()</tt> member as well as the <tt>texts()</tt> member of the
instance's gate's <a href=#206>symbol</a>.
If attributes have been assigned to an instance, <tt>texts()</tt> delivers their texts
in the form as they are currently visible.
<p>
The <tt>column()</tt> and <tt>row()</tt> members return the column and row location within
the <a href=#184>frame</a> on the sheet on which this instance is invoked.
If there is no frame on that sheet, or the instance is placed outside the frame, a <tt>'?'</tt>
(question mark) is returned.
These members can only be used in a sheet context.
<p>
The <tt>smashed</tt> member tells whether the instance is smashed. This function can also
be used to find out whether there is a detached text parameter by giving the name of
that parameter in square brackets, as in <tt>smashed["VALUE"]</tt>. This is useful
in case you want to select such a text with the <a href=#67>MOVE</a> command
by doing <tt>MOVE R5&gt;VALUE</tt>. Valid parameter names are "NAME", "VALUE",
"PART" and "GATE", as well as the names of any user defined <a href=#174>attributes</a>.
They are treated case insensitive, and they may be preceded by a <tt>'&gt;'</tt>
character.
<p>
The <tt>xrefs()</tt> member loops through the <a href=#137>contact cross-reference</a>
gates of this instance. These are only of importance if the ULP is going to create
a drawing of some sort (for instance a DXF file).
<h2>Example</h2>
<pre>
schematic(S) {
S.parts(P) {
printf("Part: %s\n", P.name);
P.instances(I) {
if (I.sheet != 0)
printf("\t%s used on sheet %d\n", I.name, I.sheet);
}
}
}
</pre>
<a name=189>
<h1>UL_JUNCTION</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>diameter</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>x, y</tt> </td><td width=20><td><a href=#166>int</a> (center point)</td></tr>
</table>
</dl>
<b>See also</b> <a href=#202>UL_SEGMENT</a>
<h2>Example</h2>
<pre>
schematic(SCH) {
SCH.sheets(SH) {
SH.nets(N) {
N.segments(SEG) {
SEG.junctions(J) {
printf("Junction: (%d %d)\n", J.x, J.y);
}
}
}
}
}
</pre>
<a name=190>
<h1>UL_LABEL</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>angle</tt> </td><td width=20><td><a href=#167>real</a> (<tt>0.0</tt>...<tt>359.9</tt>)</td></tr>
<tr><td><tt>layer</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>mirror</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>spin</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>text</tt> </td><td width=20><td><a href=#207>UL_TEXT</a></td></tr>
<tr><td><tt>x, y</tt> </td><td width=20><td><a href=#166>int</a> (origin point)</td></tr>
<tr><td><tt>xref</tt> </td><td width=20><td><a href=#166>int</a> (0=plain, 1=cross-reference)</td></tr>
</table>
<dt>
<b>Loop members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>wires()</tt> </td><td width=20><td><a href=#209>UL_WIRE</a> (see note)</td></tr>
</table>
</dl>
<b>See also</b> <a href=#202>UL_SEGMENT</a>
<h2>Note</h2>
If <tt>xref</tt> returns a non-zero value, the <tt>wires()</tt> loop member loops through
the wires that form the flag of a cross-reference label. Otherwise it is an empty loop.
<p>
The <tt>angle</tt>, <tt>layer</tt>, <tt>mirror</tt> and <tt>spin</tt> members always
return the same values as those of the UL_TEXT object returned by the <tt>text</tt>
member. The <tt>x</tt> and <tt>y</tt> members of the text return slightly offset values for
cross-reference labels (non-zero <tt>xref</tt>), otherwise they also return the same values
as the UL_LABEL.
<p>
<tt>xref</tt> is only meaningful for net labels. For bus labels it always returns 0.
<h2>Example</h2>
<pre>
sheet(SH) {
SH.nets(N) {
N.segments(S) {
S.labels(L) {
printf("Label: %d %d '%s'\n", L.x, L.y, L.text.value);
}
}
}
}
</pre>
<a name=191>
<h1>UL_LAYER</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>color</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>fill</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>name</tt> </td><td width=20><td><a href=#168>string</a> (<tt>LAYER_NAME_LENGTH</tt>)</td></tr>
<tr><td><tt>number</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>used</tt> </td><td width=20><td><a href=#166>int</a> (0=unused, 1=used)</td></tr>
<tr><td><tt>visible</tt> </td><td width=20><td><a href=#166>int</a> (0=off, 1=on)</td></tr>
</table>
</dl>
<b>See also</b> <a href=#175>UL_BOARD</a>,
<a href=#192>UL_LIBRARY</a>,
<a href=#201>UL_SCHEMATIC</a>
<h2>Constants</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>LAYER_NAME_LENGTH</tt> </td><td width=20><td>max. recommended length of a layer name (used in formatted output only)</td></tr>
<tr><td><tt>LAYER_TOP</tt> </td><td width=20><td>layer numbers</td></tr>
<tr><td><tt>LAYER_BOTTOM</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_PADS</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_VIAS</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_UNROUTED</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_DIMENSION</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_TPLACE</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_BPLACE</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_TORIGINS</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_BORIGINS</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_TNAMES</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_BNAMES</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_TVALUES</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_BVALUES</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_TSTOP</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_BSTOP</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_TCREAM</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_BCREAM</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_TFINISH</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_BFINISH</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_TGLUE</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_BGLUE</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_TTEST</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_BTEST</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_TKEEPOUT</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_BKEEPOUT</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_TRESTRICT</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_BRESTRICT</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_VRESTRICT</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_DRILLS</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_HOLES</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_MILLING</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_MEASURES</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_DOCUMENT</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_REFERENCE</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_TDOCU</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_BDOCU</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_NETS</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_BUSSES</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_PINS</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_SYMBOLS</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_NAMES</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_VALUES</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_INFO</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_GUIDE</tt> </td><td width=20><td></td></tr>
<tr><td><tt>LAYER_USER</tt> </td><td width=20><td>lowest number for user defined layers (100)</td></tr>
</table>
<h2>Example</h2>
<pre>
board(B) {
B.layers(L) printf("Layer %3d %s\n", L.number, L.name);
}
</pre>
<a name=192>
<h1>UL_LIBRARY</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>description</tt> </td><td width=20><td><a href=#168>string</a> (see note)</td></tr>
<tr><td><tt>grid</tt> </td><td width=20><td><a href=#186>UL_GRID</a></td></tr>
<tr><td><tt>headline</tt> </td><td width=20><td><a href=#168>string</a></td></tr>
<tr><td><tt>name</tt> </td><td width=20><td><a href=#168>string</a> (<tt>LIBRARY_NAME_LENGTH</tt>, see note)</td></tr>
</table>
<dt>
<b>Loop members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>devices()</tt> </td><td width=20><td><a href=#181>UL_DEVICE</a></td></tr>
<tr><td><tt>devicesets()</tt> </td><td width=20><td><a href=#182>UL_DEVICESET</a></td></tr>
<tr><td><tt>layers()</tt> </td><td width=20><td><a href=#191>UL_LAYER</a></td></tr>
<tr><td><tt>packages()</tt> </td><td width=20><td><a href=#194>UL_PACKAGE</a></td></tr>
<tr><td><tt>symbols()</tt> </td><td width=20><td><a href=#206>UL_SYMBOL</a></td></tr>
</table>
</dl>
<b>See also</b> <a href=#175>UL_BOARD</a>,
<a href=#201>UL_SCHEMATIC</a>
<h2>Constants</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>LIBRARY_NAME_LENGTH</tt> </td><td width=20><td>max. recommended length of a library name (used in formatted output only)</td></tr>
</table>
<p>
The <tt>devices()</tt> member loops through all the package variants and technologies
of all UL_DEVICESETs in the library, thus resulting in all the actual device variations
available. The <tt>devicesets()</tt> member only loops through the UL_DEVICESETs,
which in turn can be queried for their UL_DEVICE members.
<h2>Note</h2>
The <tt>description</tt> member returns the complete descriptive text as defined with
the <a href=#44>DESCRIPTION</a> command, while the <tt>headline</tt>
member returns only the first line of the description, without any <a href=#339>HTML</a> tags.
When using the <tt>description</tt> text keep in mind that it may contain newline characters (<tt>'\n'</tt>).
The <tt>description</tt> and <tt>headline</tt> information is only available within a
library drawing, not if the library is derived form a UL_BOARD or UL_SCHEMATIC context.
<p>
If the library is derived form a UL_BOARD or UL_SCHEMATIC context, <tt>name</tt> returns
the pure library name (without path or extension). Otherwise it returns the full library file name.
<h2>Example</h2>
<pre>
library(L) {
L.devices(D) printf("Dev: %s\n", D.name);
L.devicesets(D) printf("Dev: %s\n", D.name);
L.packages(P) printf("Pac: %s\n", P.name);
L.symbols(S) printf("Sym: %s\n", S.name);
}
schematic(S) {
S.libraries(L) printf("Library: %s\n", L.name);
}
</pre>
<a name=193>
<h1>UL_NET</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>class</tt> </td><td width=20><td><a href=#178>UL_CLASS</a></td></tr>
<tr><td><tt>column</tt> </td><td width=20><td><a href=#168>string</a> (see note)</td></tr>
<tr><td><tt>name</tt> </td><td width=20><td><a href=#168>string</a> (<tt>NET_NAME_LENGTH</tt>)</td></tr>
<tr><td><tt>row</tt> </td><td width=20><td><a href=#168>string</a> (see note)</td></tr>
</table>
<dt>
<b>Loop members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>pinrefs()</tt> </td><td width=20><td><a href=#198>UL_PINREF</a> (see note)</td></tr>
<tr><td><tt>segments()</tt> </td><td width=20><td><a href=#202>UL_SEGMENT</a> (see note)</td></tr>
</table>
</dl>
<b>See also</b> <a href=#203>UL_SHEET</a>,
<a href=#201>UL_SCHEMATIC</a>
<h2>Constants</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>NET_NAME_LENGTH</tt> </td><td width=20><td>max. recommended length of a net name (used in formatted output only)</td></tr>
</table>
<h2>Note</h2>
The <tt>pinrefs()</tt> loop member can only be used if the net is in a
schematic context.<br>
The <tt>segments()</tt> loop member can only be used if the net is in a
sheet context.
<p>
The <tt>column()</tt> and <tt>row()</tt> members return the column and row locations within
the <a href=#184>frame</a> on the sheet on which this net is drawn. Since a net
can extend over a certain area, each of these functions returns two values, separated by
a blank. In case of <tt>column()</tt> these are the left- and rightmost columns touched
by the net, and in case of <tt>row()</tt> it's the top- and bottommost row.
If there is no frame on that sheet, <tt>"? ?"</tt> (two question marks) is returned.
If any part of the net is placed outside the frame, either of the values may be <tt>'?'</tt> (question mark).
These members can only be used in a sheet context.
<h2>Example</h2>
<pre>
schematic(S) {
S.nets(N) {
printf("Net: %s\n", N.name);
// N.segments(SEG) will NOT work here!
}
}
schematic(S) {
S.sheets(SH) {
SH.nets(N) {
printf("Net: %s\n", N.name);
N.segments(SEG) {
SEG.wires(W) {
printf("\tWire: (%d %d) (%d %d)\n",
W.x1, W.y1, W.x2, W.y2);
}
}
}
}
}
</pre>
<a name=194>
<h1>UL_PACKAGE</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>area</tt> </td><td width=20><td><a href=#173>UL_AREA</a></td></tr>
<tr><td><tt>description</tt> </td><td width=20><td><a href=#168>string</a></td></tr>
<tr><td><tt>headline</tt> </td><td width=20><td><a href=#168>string</a></td></tr>
<tr><td><tt>library</tt> </td><td width=20><td><a href=#168>string</a></td></tr>
<tr><td><tt>name</tt> </td><td width=20><td><a href=#168>string</a> (<tt>PACKAGE_NAME_LENGTH</tt>)</td></tr>
</table>
<dt>
<b>Loop members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>circles()</tt> </td><td width=20><td><a href=#177>UL_CIRCLE</a></td></tr>
<tr><td><tt>contacts()</tt> </td><td width=20><td><a href=#179>UL_CONTACT</a></td></tr>
<tr><td><tt>frames()</tt> </td><td width=20><td><a href=#184>UL_FRAME</a></td></tr>
<tr><td><tt>holes()</tt> </td><td width=20><td><a href=#187>UL_HOLE</a></td></tr>
<tr><td><tt>polygons()</tt> </td><td width=20><td><a href=#199>UL_POLYGON</a></td></tr>
<tr><td><tt>rectangles()</tt> </td><td width=20><td><a href=#200>UL_RECTANGLE</a></td></tr>
<tr><td><tt>texts()</tt> </td><td width=20><td><a href=#207>UL_TEXT</a> (see note)</td></tr>
<tr><td><tt>wires()</tt> </td><td width=20><td><a href=#209>UL_WIRE</a></td></tr>
</table>
</dl>
<b>See also</b> <a href=#181>UL_DEVICE</a>,
<a href=#183>UL_ELEMENT</a>,
<a href=#192>UL_LIBRARY</a>
<h2>Constants</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>PACKAGE_NAME_LENGTH</tt> </td><td width=20><td>max. recommended length of a package name (used in formatted output only)</td></tr>
</table>
<h2>Note</h2>
The <tt>description</tt> member returns the complete descriptive text as defined with
the <a href=#44>DESCRIPTION</a> command, while the <tt>headline</tt>
member returns only the first line of the description, without any <a href=#339>HTML</a> tags.
When using the <tt>description</tt> text keep in mind that it may contain newline characters (<tt>'\n'</tt>).
<p>
If the UL_PACKAGE is derived from a UL_ELEMENT, the <tt>texts()</tt> member only loops through the
non-detached texts of that element.
<h2>Example</h2>
<pre>
library(L) {
L.packages(PAC) {
printf("Package: %s\n", PAC.name);
PAC.contacts(C) {
if (C.pad)
printf("\tPad: %s, (%d %d)\n",
C.name, C.pad.x, C.pad.y);
else if (C.smd)
printf("\tSmd: %s, (%d %d)\n",
C.name, C.smd.x, C.smd.y);
}
}
}
board(B) {
B.elements(E) {
printf("Element: %s, Package: %s\n", E.name, E.package.name);
}
}
</pre>
<a name=195>
<h1>UL_PAD</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>angle</tt> </td><td width=20><td><a href=#167>real</a> (<tt>0.0</tt>...<tt>359.9</tt>)</td></tr>
<tr><td><tt>diameter[layer]</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>drill</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>drillsymbol</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>elongation</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>flags</tt> </td><td width=20><td><a href=#166>int</a> (<tt>PAD_FLAG_...</tt>)</td></tr>
<tr><td><tt>name</tt> </td><td width=20><td><a href=#168>string</a> (<tt>PAD_NAME_LENGTH</tt>)</td></tr>
<tr><td><tt>shape[layer]</tt> </td><td width=20><td><a href=#166>int</a> (<tt>PAD_SHAPE_...</tt>)</td></tr>
<tr><td><tt>signal</tt> </td><td width=20><td><a href=#168>string</a></td></tr>
<tr><td><tt>x, y</tt> </td><td width=20><td><a href=#166>int</a> (center point, see note)</td></tr>
</table>
</dl>
<b>See also</b> <a href=#194>UL_PACKAGE</a>,
<a href=#179>UL_CONTACT</a>,
<a href=#205>UL_SMD</a>
<h2>Constants</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>PAD_FLAG_STOP</tt> </td><td width=20><td>generate stop mask</td></tr>
<tr><td><tt>PAD_FLAG_THERMALS</tt> </td><td width=20><td>generate thermals</td></tr>
<tr><td><tt>PAD_FLAG_FIRST</tt> </td><td width=20><td>use special "first pad" shape</td></tr>
</table>
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>PAD_SHAPE_SQUARE</tt> </td><td width=20><td>square</td></tr>
<tr><td><tt>PAD_SHAPE_ROUND</tt> </td><td width=20><td>round</td></tr>
<tr><td><tt>PAD_SHAPE_OCTAGON</tt> </td><td width=20><td>octagon</td></tr>
<tr><td><tt>PAD_SHAPE_LONG</tt> </td><td width=20><td>long</td></tr>
<tr><td><tt>PAD_SHAPE_OFFSET</tt> </td><td width=20><td>offset</td></tr>
<tr><td><tt>PAD_SHAPE_ANNULUS</tt> </td><td width=20><td>annulus (only if supply layers are used)</td></tr>
<tr><td><tt>PAD_SHAPE_THERMAL</tt> </td><td width=20><td>thermal (only if supply layers are used)</td></tr>
</table>
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>PAD_NAME_LENGTH</tt> </td><td width=20><td>max. recommended length of a pad name (same as <tt>CONTACT_NAME_LENGTH</tt>)</td></tr>
</table>
<h2>Note</h2>
The parameters of the pad depend on the context in which it is accessed:
<ul>
<li>if the pad is derived from a UL_LIBRARY context, the coordinates (<tt>x, y</tt>) and <tt>angle</tt> will be the same as
defined in the package drawing
<li>in all other cases, they will have the actual values from the board
</ul>
<p>
The diameter and shape of the pad depend on the layer for which they shall be retrieved,
because they may be different in each layer depending on the <a href=#133>Design Rules</a>.
If one of the <a href=#191>layers</a> LAYER_TOP...LAYER_BOTTOM, LAYER_TSTOP or LAYER_BSTOP
is given as the index to the diameter or shape data member, the resulting value will be calculated
according to the Design Rules. If LAYER_PADS is given, the raw value as defined in the library will
be returned.
<p>
<tt>drillsymbol</tt> returns the number of the drill symbol that has been assigned
to this drill diameter (see the manual for a list of defined drill symbols).
A value of <tt>0</tt> means that no symbol has been assigned to this drill diameter.
<p>
<tt>angle</tt> defines how many degrees the pad is rotated counterclockwise
around its center.
<p>
<tt>elongation</tt> is only valid for shapes PAD_SHAPE_LONG and PAD_SHAPE_OFFSET and
defines how many percent the long side of such a pad is longer than its small side.
This member returns 0 for any other pad shapes.
<p>
The value returned by <tt>flags</tt> must be masked with the <tt>PAD_FLAG_...</tt>
constants to determine the individual flag settings, as in
<pre>
if (pad.flags &amp; PAD_FLAG_STOP) {
...
}
</pre>
Note that if your ULP just wants to draw the objects, you don't need to check these
flags explicitly. The <tt>diameter[]</tt> and <tt>shape[]</tt> members will return
the proper data; for instance, if <tt>PAD_FLAG_STOP</tt> is set, <tt>diameter[LAYER_TSTOP]</tt>
will return <tt>0</tt>, which should result in nothing being drawn in that layer.
The <tt>flags</tt> member is mainly for ULPs that want to create script files that
create library objects.
<h2>Example</h2>
<pre>
library(L) {
L.packages(PAC) {
PAC.contacts(C) {
if (C.pad)
printf("Pad: '%s', (%d %d), d=%d\n",
C.name, C.pad.x, C.pad.y, C.pad.diameter[LAYER_BOTTOM]);
}
}
}
</pre>
<a name=196>
<h1>UL_PART</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>attribute[]</tt> </td><td width=20><td><a href=#168>string</a> (see note)</td></tr>
<tr><td><tt>device</tt> </td><td width=20><td><a href=#181>UL_DEVICE</a></td></tr>
<tr><td><tt>deviceset</tt> </td><td width=20><td><a href=#182>UL_DEVICESET</a></td></tr>
<tr><td><tt>name</tt> </td><td width=20><td><a href=#168>string</a> (<tt>PART_NAME_LENGTH</tt>)</td></tr>
<tr><td><tt>value</tt> </td><td width=20><td><a href=#168>string</a> (<tt>PART_VALUE_LENGTH</tt>)</td></tr>
</table>
<dt>
<b>Loop members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>attributes()</tt> </td><td width=20><td><a href=#174>UL_ATTRIBUTE</a> (see note)</td></tr>
<tr><td><tt>instances()</tt> </td><td width=20><td><a href=#188>UL_INSTANCE</a> (see note)</td></tr>
</table>
</dl>
<b>See also</b> <a href=#201>UL_SCHEMATIC</a>,
<a href=#203>UL_SHEET</a>
<h2>Constants</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>PART_NAME_LENGTH</tt> </td><td width=20><td>max. recommended length of a part name (used in formatted output only)</td></tr>
<tr><td><tt>PART_VALUE_LENGTH</tt> </td><td width=20><td>max. recommended length of a part value (used in formatted output only)</td></tr>
</table>
<h2>Note</h2>
The <tt>attribute[]</tt> member can be used to query a UL_PART for the value of a given
attribute (see the second example below). The returned string is empty if there is no
attribute by the given name, or if this attribute is explicitly empty.
<p>
When looping through the <tt>attributes()</tt> of a UL_PART, only the <tt>name</tt>,
<tt>value</tt>, <tt>defaultvalue</tt> and <tt>constant</tt> members of the resulting
UL_ATTRIBUTE objects are valid.
<p>
If the part is in a sheet context, the <tt>instances()</tt> loop member
loops only through those instances that are actually used on that sheet.
If the part is in a schematic context, all instances are looped through.
<h2>Example</h2>
<pre>
schematic(S) {
S.parts(P) printf("Part: %s\n", P.name);
}
</pre>
<pre>
schematic(SCH) {
SCH.parts(P) {
if (P.attribute["REMARK"])
printf("%s: %s\n", P.name, P.attribute["REMARK"]);
}
}
</pre>
<a name=197>
<h1>UL_PIN</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>angle</tt> </td><td width=20><td><a href=#167>real</a> (<tt>0</tt>, <tt>90</tt>, <tt>180</tt> and <tt>270</tt>)</td></tr>
<tr><td><tt>contact</tt> </td><td width=20><td><a href=#179>UL_CONTACT</a> (see note)</td></tr>
<tr><td><tt>direction</tt> </td><td width=20><td><a href=#166>int</a> (<tt>PIN_DIRECTION_...</tt>)</td></tr>
<tr><td><tt>function</tt> </td><td width=20><td><a href=#166>int</a> (<tt>PIN_FUNCTION_FLAG_...</tt>)</td></tr>
<tr><td><tt>length</tt> </td><td width=20><td><a href=#166>int</a> (<tt>PIN_LENGTH_...</tt>)</td></tr>
<tr><td><tt>name</tt> </td><td width=20><td><a href=#168>string</a> (<tt>PIN_NAME_LENGTH</tt>)</td></tr>
<tr><td><tt>net</tt> </td><td width=20><td><a href=#168>string</a> (see note)</td></tr>
<tr><td><tt>swaplevel</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>visible</tt> </td><td width=20><td><a href=#166>int</a> (<tt>PIN_VISIBLE_FLAG_...</tt>)</td></tr>
<tr><td><tt>x, y</tt> </td><td width=20><td><a href=#166>int</a> (connection point)</td></tr>
</table>
<dt>
<b>Loop members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>circles()</tt> </td><td width=20><td><a href=#177>UL_CIRCLE</a></td></tr>
<tr><td><tt>texts()</tt> </td><td width=20><td><a href=#207>UL_TEXT</a></td></tr>
<tr><td><tt>wires()</tt> </td><td width=20><td><a href=#209>UL_WIRE</a></td></tr>
</table>
</dl>
<b>See also</b> <a href=#206>UL_SYMBOL</a>,
<a href=#198>UL_PINREF</a>,
<a href=#180>UL_CONTACTREF</a>
<h2>Constants</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>PIN_DIRECTION_NC</tt> </td><td width=20><td>not connected</td></tr>
<tr><td><tt>PIN_DIRECTION_IN</tt> </td><td width=20><td>input</td></tr>
<tr><td><tt>PIN_DIRECTION_OUT</tt> </td><td width=20><td>output (totem-pole)</td></tr>
<tr><td><tt>PIN_DIRECTION_IO</tt> </td><td width=20><td>in/output (bidirectional)</td></tr>
<tr><td><tt>PIN_DIRECTION_OC</tt> </td><td width=20><td>open collector</td></tr>
<tr><td><tt>PIN_DIRECTION_PWR</tt> </td><td width=20><td>power input pin</td></tr>
<tr><td><tt>PIN_DIRECTION_PAS</tt> </td><td width=20><td>passive</td></tr>
<tr><td><tt>PIN_DIRECTION_HIZ</tt> </td><td width=20><td>high impedance output</td></tr>
<tr><td><tt>PIN_DIRECTION_SUP</tt> </td><td width=20><td>supply pin</td></tr>
</table>
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>PIN_FUNCTION_FLAG_NONE</tt> </td><td width=20><td>no symbol</td></tr>
<tr><td><tt>PIN_FUNCTION_FLAG_DOT</tt> </td><td width=20><td>inverter symbol</td></tr>
<tr><td><tt>PIN_FUNCTION_FLAG_CLK</tt> </td><td width=20><td>clock symbol</td></tr>
</table>
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>PIN_LENGTH_POINT</tt> </td><td width=20><td>no wire</td></tr>
<tr><td><tt>PIN_LENGTH_SHORT</tt> </td><td width=20><td>0.1 inch wire</td></tr>
<tr><td><tt>PIN_LENGTH_MIDDLE</tt> </td><td width=20><td>0.2 inch wire</td></tr>
<tr><td><tt>PIN_LENGTH_LONG</tt> </td><td width=20><td>0.3 inch wire</td></tr>
</table>
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>PIN_NAME_LENGTH</tt> </td><td width=20><td>max. recommended length of a pin name (used in formatted output only)</td></tr>
</table>
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>PIN_VISIBLE_FLAG_OFF</tt> </td><td width=20><td>no name drawn</td></tr>
<tr><td><tt>PIN_VISIBLE_FLAG_PAD</tt> </td><td width=20><td>pad name drawn</td></tr>
<tr><td><tt>PIN_VISIBLE_FLAG_PIN</tt> </td><td width=20><td>pin name drawn</td></tr>
</table>
<h2>Note</h2>
The <tt>contact</tt> data member returns the <a href=#179>contact</a>
that has been assigned to the pin through a <a href=#40>CONNECT</a>
command. It can be used as a boolean function to check whether a contact has been
assigned to a pin (see example below).
<p>
The coordinates (and layer, in case of an SMD) of the contact returned by
the <tt>contact</tt> data member depend on the context in which it is called:
<ul>
<li>if the pin is derived from a UL_PART that is used on a sheet, and if there
is a corresponding element on the board, the resulting contact will have
the coordinates as used on the board
<li>in all other cases, the coordinates of the contact will be the same as
defined in the package drawing
</ul>
The <tt>name</tt> data member always returns the name of the pin as it was defined
in the library, with any <tt>'@'</tt> character for pins with the same name left intact
(see the <a href=#75>PIN</a> command for details).<br>
The <tt>texts</tt> loop member, on the other hand, returns the pin name (if it is
visible) in the same way as it is displayed in the current drawing type.
<p>
The <tt>net</tt> data member returns the name of the net to which this pin is connected
(only available in a schematic context).
<h2>Example</h2>
<pre>
library(L) {
L.symbols(S) {
printf("Symbol: %s\n", S.name);
S.pins(P) {
printf("\tPin: %s, (%d %d)", P.name, P.x, P.y);
if (P.direction == PIN_DIRECTION_IN)
printf(" input");
if ((P.function &amp; PIN_FUNCTION_FLAG_DOT) != 0)
printf(" inverted");
printf("\n");
}
}
L.devices(D) {
D.gates(G) {
G.symbol.pins(P) {
if (!P.contact)
printf("Unconnected pin: %s/%s/%s\n", D.name, G.name, P.name);
}
}
}
}
</pre>
<a name=198>
<h1>UL_PINREF</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>instance</tt> </td><td width=20><td><a href=#188>UL_INSTANCE</a></td></tr>
<tr><td><tt>part</tt> </td><td width=20><td><a href=#196>UL_PART</a></td></tr>
<tr><td><tt>pin</tt> </td><td width=20><td><a href=#197>UL_PIN</a></td></tr>
</table>
</dl>
<b>See also</b> <a href=#202>UL_SEGMENT</a>,
<a href=#180>UL_CONTACTREF</a>
<h2>Example</h2>
<pre>
schematic(SCH) {
SCH.sheets(SH) {
printf("Sheet: %d\n", SH.number);
SH.nets(N) {
printf("\tNet: %s\n", N.name);
N.segments(SEG) {
SEG.pinrefs(P) {
printf("connected to: %s, %s, %s\n",
P.part.name, P.instance.name, P.pin.name);
}
}
}
}
}
</pre>
<a name=199>
<h1>UL_POLYGON</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>isolate</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>layer</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>orphans</tt> </td><td width=20><td><a href=#166>int</a> (0=off, 1=on)</td></tr>
<tr><td><tt>pour</tt> </td><td width=20><td><a href=#166>int</a> (<tt>POLYGON_POUR_...</tt>)</td></tr>
<tr><td><tt>rank</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>spacing</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>thermals</tt> </td><td width=20><td><a href=#166>int</a> (0=off, 1=on)</td></tr>
<tr><td><tt>width</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
</table>
<dt>
<b>Loop members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>contours()</tt> </td><td width=20><td><a href=#209>UL_WIRE</a> (see note)</td></tr>
<tr><td><tt>fillings()</tt> </td><td width=20><td><a href=#209>UL_WIRE</a></td></tr>
<tr><td><tt>wires()</tt> </td><td width=20><td><a href=#209>UL_WIRE</a></td></tr>
</table>
</dl>
<b>See also</b> <a href=#175>UL_BOARD</a>,
<a href=#194>UL_PACKAGE</a>,
<a href=#203>UL_SHEET</a>,
<a href=#204>UL_SIGNAL</a>,
<a href=#206>UL_SYMBOL</a>
<h2>Constants</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>POLYGON_POUR_SOLID</tt> </td><td width=20><td>solid</td></tr>
<tr><td><tt>POLYGON_POUR_HATCH</tt> </td><td width=20><td>hatch</td></tr>
</table>
<h2>Note</h2>
The <tt>contours()</tt> and <tt>fillings()</tt> loop members loop through the
wires that are used to draw the calculated polygon if it is part of a signal and
the polygon has been calculated by the <a href=#81>RATSNEST</a>
command. The <tt>wires()</tt> loop member always loops through the polygon
wires as they were drawn by the user. For an uncalculated signal polygon
<tt>contours()</tt> does the same as <tt>wires()</tt>, and <tt>fillings()</tt>
does nothing.
<p>
If the <tt>contours()</tt> loop member is called without a second parameter,
it loops through all of the contour wires, regardless whether they
belong to a positive or a negative polygon. If you are interested in getting
the positive and negative contour wires separately, you can call <tt>contours()</tt>
with an additional integer parameter (see the second example below). The sign of
that parameter determines whether a positive or a negative polygon will be handled,
and the value indicates the index of that polygon. If there is no polygon with the
given index, the statement will not be executed. Another advantage of this method
is that you don't need to determine the beginning and end of a particular polygon
yourself (by comparing coordinates). For any given index, the statement will be
executed for all the wires of that polygon.
With the second parameter <tt>0</tt> the behavior is the same
as without a second parameter.
<h2>Polygon width</h2>
When using the <tt>fillings()</tt> loop member to get the fill wires of a solid
polygon, make sure the <i>width</i> of the polygon is not zero (actually it should
be quite a bit larger than zero, for example at least the hardware resolution of
the output device you are going to draw on). <b>Filling a polygon with zero width
may result in enormous amounts of data, since it will be calculated with the
smallest editor resolution of 1/10000mm!</b>
<h2>Partial polygons</h2>
A calculated signal polygon may consist of several distinct parts (called
<i>positive</i> polygons), each of which can contain extrusions (<i>negative</i>
polygons) resulting from other objects being subtracted from the polygon.
Negative polygons can again contain other positive polygons and so on.
<p>
The wires looped through by <tt>contours()</tt> always start with a positive
polygon. To find out where one partial polygon ends and the next one begins, simply
store the (x1,y1) coordinates of the first wire and check them against
(x2,y2) of every following wire. As soon as these are equal, the last wire
of a partial polygon has been found. It is also guaranteed that the second
point (x2,y2) of one wire is identical to the first point (x1,y1) of the
next wire in that partial polygon.
<p>
To find out where the "inside" and the "outside" of the polygon lays,
take any contour wire and imagine looking from its point (x1,y1) to (x2,y2).
The "inside" of the polygon is always on the right side of the wire.
Note that if you simply want to draw the polygon you won't need all these
details.
<h2>Example</h2>
<pre>
board(B) {
B.signals(S) {
S.polygons(P) {
int x0, y0, first = 1;
P.contours(W) {
if (first) {
// a new partial polygon is starting
x0 = W.x1;
y0 = W.y1;
}
// ...
// do something with the wire
// ...
if (first)
first = 0;
else if (W.x2 == x0 &amp;&amp; W.y2 == y0) {
// this was the last wire of the partial polygon,
// so the next wire (if any) will be the first wire
// of the next partial polygon
first = 1;
}
}
}
}
}
</pre>
<p>
<pre>
board(B) {
B.signals(S) {
S.polygons(P) {
// handle only the "positive" polygons:
int i = 1;
int active;
do {
active = 0;
P.contours(W, i) {
active = 1;
// do something with the wire
}
i++;
} while (active);
}
}
}
</pre>
<a name=200>
<h1>UL_RECTANGLE</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>angle</tt> </td><td width=20><td><a href=#167>real</a> (<tt>0.0</tt>...<tt>359.9</tt>)</td></tr>
<tr><td><tt>layer</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>x1, y1</tt> </td><td width=20><td><a href=#166>int</a> (lower left corner)</td></tr>
<tr><td><tt>x2, y2</tt> </td><td width=20><td><a href=#166>int</a> (upper right corner)</td></tr>
</table>
</dl>
<b>See also</b> <a href=#175>UL_BOARD</a>,
<a href=#194>UL_PACKAGE</a>,
<a href=#203>UL_SHEET</a>,
<a href=#206>UL_SYMBOL</a>
<p>
<tt>angle</tt> defines how many degrees the rectangle is rotated counterclockwise
around its center. The center coordinates are given by <tt>(x1+x2)/2</tt> and <tt>(y1+y2)/2</tt>.
<h2>Example</h2>
<pre>
board(B) {
B.rectangles(R) {
printf("Rectangle: (%d %d), (%d %d)\n",
R.x1, R.y1, R.x2, R.y2);
}
}
</pre>
<a name=201>
<h1>UL_SCHEMATIC</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>grid</tt> </td><td width=20><td><a href=#186>UL_GRID</a></td></tr>
<tr><td><tt>name</tt> </td><td width=20><td><a href=#168>string</a> (see note)</td></tr>
<tr><td><tt>xreflabel</tt> </td><td width=20><td><a href=#168>string</a></td></tr>
</table>
<dt>
<b>Loop members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>attributes()</tt> </td><td width=20><td><a href=#174>UL_ATTRIBUTE</a> (see note)</td></tr>
<tr><td><tt>classes()</tt> </td><td width=20><td><a href=#178>UL_CLASS</a></td></tr>
<tr><td><tt>layers()</tt> </td><td width=20><td><a href=#191>UL_LAYER</a></td></tr>
<tr><td><tt>libraries()</tt> </td><td width=20><td><a href=#192>UL_LIBRARY</a></td></tr>
<tr><td><tt>nets()</tt> </td><td width=20><td><a href=#193>UL_NET</a></td></tr>
<tr><td><tt>parts()</tt> </td><td width=20><td><a href=#196>UL_PART</a></td></tr>
<tr><td><tt>sheets()</tt> </td><td width=20><td><a href=#203>UL_SHEET</a></td></tr>
</table>
</dl>
<b>See also</b> <a href=#175>UL_BOARD</a>,
<a href=#192>UL_LIBRARY</a>
<h2>Note</h2>
The <tt>name</tt> member returns the full file name, including the directory.
<p>
The <tt>xreflabel</tt> member returns the format string used to display
<a href=#60>cross-reference labels</a>.
<p>
The <tt>attributes()</tt> loop member loops through the <i>global</i> attributes.
<h2>Example</h2>
<pre>
schematic(S) {
S.parts(P) printf("Part: %s\n", P.name);
}
</pre>
<a name=202>
<h1>UL_SEGMENT</h1>
<dl>
<dt>
<b>Loop members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>junctions()</tt> </td><td width=20><td><a href=#189>UL_JUNCTION</a> (see note)</td></tr>
<tr><td><tt>labels()</tt> </td><td width=20><td><a href=#190>UL_LABEL</a></td></tr>
<tr><td><tt>pinrefs()</tt> </td><td width=20><td><a href=#198>UL_PINREF</a> (see note)</td></tr>
<tr><td><tt>texts()</tt> </td><td width=20><td><a href=#207>UL_TEXT</a> (deprecated, see note)</td></tr>
<tr><td><tt>wires()</tt> </td><td width=20><td><a href=#209>UL_WIRE</a></td></tr>
</table>
</dl>
<b>See also</b> <a href=#176>UL_BUS</a>,
<a href=#193>UL_NET</a>
<h2>Note</h2>
The <tt>junctions()</tt> and <tt>pinrefs()</tt> loop members are only available
for net segments.
<p>
The <tt>texts()</tt> loop member was used in older EAGLE versions to loop through
the labels of a segment, and is only present for compatibility. It will not
deliver the text of cross-reference labels at the correct position. Use the
<tt>labels()</tt> loop member to access a segment's labels.
<h2>Example</h2>
<pre>
schematic(SCH) {
SCH.sheets(SH) {
printf("Sheet: %d\n", SH.number);
SH.nets(N) {
printf("\tNet: %s\n", N.name);
N.segments(SEG) {
SEG.pinrefs(P) {
printf("connected to: %s, %s, %s\n",
P.part.name, P.instance.name, P.pin.name);
}
}
}
}
}
</pre>
<a name=203>
<h1>UL_SHEET</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>area</tt> </td><td width=20><td><a href=#173>UL_AREA</a></td></tr>
<tr><td><tt>number</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
</table>
<dt>
<b>Loop members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>busses()</tt> </td><td width=20><td><a href=#176>UL_BUS</a></td></tr>
<tr><td><tt>circles()</tt> </td><td width=20><td><a href=#177>UL_CIRCLE</a></td></tr>
<tr><td><tt>frames()</tt> </td><td width=20><td><a href=#184>UL_FRAME</a></td></tr>
<tr><td><tt>nets()</tt> </td><td width=20><td><a href=#193>UL_NET</a></td></tr>
<tr><td><tt>parts()</tt> </td><td width=20><td><a href=#196>UL_PART</a></td></tr>
<tr><td><tt>polygons()</tt> </td><td width=20><td><a href=#199>UL_POLYGON</a></td></tr>
<tr><td><tt>rectangles()</tt> </td><td width=20><td><a href=#200>UL_RECTANGLE</a></td></tr>
<tr><td><tt>texts()</tt> </td><td width=20><td><a href=#207>UL_TEXT</a></td></tr>
<tr><td><tt>wires()</tt> </td><td width=20><td><a href=#209>UL_WIRE</a></td></tr>
</table>
</dl>
<b>See also</b> <a href=#201>UL_SCHEMATIC</a>
<h2>Example</h2>
<pre>
schematic(SCH) {
SCH.sheets(S) {
printf("Sheet: %d\n", S.number);
}
}
</pre>
<a name=204>
<h1>UL_SIGNAL</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>airwireshidden</tt></td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>class</tt> </td><td width=20><td><a href=#178>UL_CLASS</a></td></tr>
<tr><td><tt>name</tt> </td><td width=20><td><a href=#168>string</a> (<tt>SIGNAL_NAME_LENGTH</tt>)</td></tr>
</table>
<dt>
<b>Loop members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>contactrefs()</tt> </td><td width=20><td><a href=#180>UL_CONTACTREF</a></td></tr>
<tr><td><tt>polygons()</tt> </td><td width=20><td><a href=#199>UL_POLYGON</a></td></tr>
<tr><td><tt>vias()</tt> </td><td width=20><td><a href=#208>UL_VIA</a></td></tr>
<tr><td><tt>wires()</tt> </td><td width=20><td><a href=#209>UL_WIRE</a></td></tr>
</table>
</dl>
<b>See also</b> <a href=#175>UL_BOARD</a>
<h2>Constants</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>SIGNAL_NAME_LENGTH</tt> </td><td width=20><td>max. recommended length of a signal name (used in formatted output only)</td></tr>
</table>
<h2>Example</h2>
<pre>
board(B) {
B.signals(S) printf("Signal: %s\n", S.name);
}
</pre>
<a name=205>
<h1>UL_SMD</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>angle</tt> </td><td width=20><td><a href=#167>real</a> (<tt>0.0</tt>...<tt>359.9</tt>)</td></tr>
<tr><td><tt>dx[layer], dy[layer]</tt> </td><td width=20><td><a href=#166>int</a> (size)</td></tr>
<tr><td><tt>flags</tt> </td><td width=20><td><a href=#166>int</a> (<tt>SMD_FLAG_...</tt>)</td></tr>
<tr><td><tt>layer</tt> </td><td width=20><td><a href=#166>int</a> (see note)</td></tr>
<tr><td><tt>name</tt> </td><td width=20><td><a href=#168>string</a> (<tt>SMD_NAME_LENGTH</tt>)</td></tr>
<tr><td><tt>roundness</tt> </td><td width=20><td><a href=#166>int</a> (see note)</td></tr>
<tr><td><tt>signal</tt> </td><td width=20><td><a href=#168>string</a></td></tr>
<tr><td><tt>x, y</tt> </td><td width=20><td><a href=#166>int</a> (center point, see note)</td></tr>
</table>
</dl>
<b>See also</b> <a href=#194>UL_PACKAGE</a>,
<a href=#179>UL_CONTACT</a>,
<a href=#195>UL_PAD</a>
<h2>Constants</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>SMD_FLAG_STOP</tt> </td><td width=20><td>generate stop mask</td></tr>
<tr><td><tt>SMD_FLAG_THERMALS</tt> </td><td width=20><td>generate thermals</td></tr>
<tr><td><tt>SMD_FLAG_CREAM</tt> </td><td width=20><td>generate cream mask</td></tr>
</table>
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>SMD_NAME_LENGTH</tt> </td><td width=20><td>max. recommended length of an smd name (same as <tt>CONTACT_NAME_LENGTH</tt>)</td></tr>
</table>
<h2>Note</h2>
The parameters of the smd depend on the context in which it is accessed:
<ul>
<li>if the smd is derived from a UL_LIBRARY context, the coordinates (<tt>x, y</tt>), <tt>angle</tt>, <tt>layer</tt> and <tt>roundness</tt> of the smd will be the same as
defined in the package drawing
<li>in all other cases, they will have the actual values from the board
</ul>
If the <tt>dx</tt> and <tt>dy</tt> data members are called with an optional layer index,
the data for that layer is returned according to the <a href=#133>Design Rules</a>.
Valid <a href=#191>layers</a> are LAYER_TOP, LAYER_TSTOP and LAYER_TCREAM for a via in the Top layer, and
LAYER_BOTTOM, LAYER_BSTOP and LAYER_BCREAM for a via in the Bottom layer, respectively.
<p>
<tt>angle</tt> defines how many degrees the smd is rotated counterclockwise
around its center.
<p>
The value returned by <tt>flags</tt> must be masked with the <tt>SMD_FLAG_...</tt>
constants to determine the individual flag settings, as in
<pre>
if (smd.flags &amp; SMD_FLAG_STOP) {
...
}
</pre>
Note that if your ULP just wants to draw the objects, you don't need to check these
flags explicitly. The <tt>dx[]</tt> and <tt>dy[]</tt> members will return
the proper data; for instance, if <tt>SMD_FLAG_STOP</tt> is set, <tt>dx[LAYER_TSTOP]</tt>
will return <tt>0</tt>, which should result in nothing being drawn in that layer.
The <tt>flags</tt> member is mainly for ULPs that want to create script files that
create library objects.
<h2>Example</h2>
<pre>
library(L) {
L.packages(PAC) {
PAC.contacts(C) {
if (C.smd)
printf("Smd: '%s', (%d %d), dx=%d, dy=%d\n",
C.name, C.smd.x, C.smd.y, C.smd.dx, C.smd.dy);
}
}
}
</pre>
<a name=206>
<h1>UL_SYMBOL</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>area</tt> </td><td width=20><td><a href=#173>UL_AREA</a></td></tr>
<tr><td><tt>library</tt> </td><td width=20><td><a href=#168>string</a></td></tr>
<tr><td><tt>name</tt> </td><td width=20><td><a href=#168>string</a> (<tt>SYMBOL_NAME_LENGTH</tt>)</td></tr>
</table>
<dt>
<b>Loop members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>circles()</tt> </td><td width=20><td><a href=#177>UL_CIRCLE</a></td></tr>
<tr><td><tt>frames()</tt> </td><td width=20><td><a href=#184>UL_FRAME</a></td></tr>
<tr><td><tt>rectangles()</tt> </td><td width=20><td><a href=#200>UL_RECTANGLE</a></td></tr>
<tr><td><tt>pins()</tt> </td><td width=20><td><a href=#197>UL_PIN</a></td></tr>
<tr><td><tt>polygons()</tt> </td><td width=20><td><a href=#199>UL_POLYGON</a></td></tr>
<tr><td><tt>texts()</tt> </td><td width=20><td><a href=#207>UL_TEXT</a> (see note)</td></tr>
<tr><td><tt>wires()</tt> </td><td width=20><td><a href=#209>UL_WIRE</a></td></tr>
</table>
</dl>
<b>See also</b> <a href=#185>UL_GATE</a>,
<a href=#192>UL_LIBRARY</a>
<h2>Constants</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>SYMBOL_NAME_LENGTH</tt> </td><td width=20><td>max. recommended length of a symbol name (used in formatted output only)</td></tr>
</table>
<h2>Note</h2>
If the UL_SYMBOL is derived from a UL_INSTANCE, the <tt>texts()</tt> member only loops through the
non-detached texts of that instance.
<h2>Example</h2>
<pre>
library(L) {
L.symbols(S) printf("Sym: %s\n", S.name);
}
</pre>
<a name=207>
<h1>UL_TEXT</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>angle</tt> </td><td width=20><td><a href=#167>real</a> (<tt>0.0</tt>...<tt>359.9</tt>)</td></tr>
<tr><td><tt>font</tt> </td><td width=20><td><a href=#166>int</a> (<tt>FONT_...</tt>)</td></tr>
<tr><td><tt>layer</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>mirror</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>ratio</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>size</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>spin</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>value</tt> </td><td width=20><td><a href=#168>string</a></td></tr>
<tr><td><tt>x, y</tt> </td><td width=20><td><a href=#166>int</a> (origin point)</td></tr>
</table>
<dt>
<b>Loop members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>wires()</tt> </td><td width=20><td><a href=#209>UL_WIRE</a> (see note)</td></tr>
</table>
</dl>
<b>See also</b> <a href=#175>UL_BOARD</a>,
<a href=#194>UL_PACKAGE</a>,
<a href=#203>UL_SHEET</a>,
<a href=#206>UL_SYMBOL</a>
<h2>Constants</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>FONT_VECTOR</tt> </td><td width=20><td>vector font</td></tr>
<tr><td><tt>FONT_PROPORTIONAL</tt> </td><td width=20><td>proportional font</td></tr>
<tr><td><tt>FONT_FIXED</tt> </td><td width=20><td>fixed font</td></tr>
</table>
<h2>Note</h2>
The <tt>wires()</tt> loop member always accesses the individual wires the text
is composed of when using the vector font, even if the actual font is not
<tt>FONT_VECTOR</tt>.
<p>
If the UL_TEXT is derived from a UL_ELEMENT or UL_INSTANCE context, the member
values will be those of the actual text as located in the board or sheet drawing.
<h2>Example</h2>
<pre>
board(B) {
B.texts(T) {
printf("Text: %s\n", T.value);
}
}
</pre>
<a name=208>
<h1>UL_VIA</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>diameter[layer]</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>drill</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>drillsymbol</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>end</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>flags</tt> </td><td width=20><td><a href=#166>int</a> (<tt>VIA_FLAG_...</tt>)</td></tr>
<tr><td><tt>shape[layer]</tt> </td><td width=20><td><a href=#166>int</a> (<tt>VIA_SHAPE_...</tt>)</td></tr>
<tr><td><tt>start</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>x, y</tt> </td><td width=20><td><a href=#166>int</a> (center point)</td></tr>
</table>
</dl>
<b>See also</b> <a href=#204>UL_SIGNAL</a>
<h2>Constants</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>VIA_FLAG_STOP</tt> </td><td width=20><td>always generate stop mask</td></tr>
</table>
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>VIA_SHAPE_SQUARE</tt> </td><td width=20><td>square</td></tr>
<tr><td><tt>VIA_SHAPE_ROUND</tt> </td><td width=20><td>round</td></tr>
<tr><td><tt>VIA_SHAPE_OCTAGON</tt> </td><td width=20><td>octagon</td></tr>
<tr><td><tt>VIA_SHAPE_ANNULUS</tt> </td><td width=20><td>annulus</td></tr>
<tr><td><tt>VIA_SHAPE_THERMAL</tt> </td><td width=20><td>thermal</td></tr>
</table>
<h2>Note</h2>
The diameter and shape of the via depend on the layer for which they shall be retrieved,
because they may be different in each layer depending on the <a href=#133>Design Rules</a>.
If one of the <a href=#191>layers</a> LAYER_TOP...LAYER_BOTTOM, LAYER_TSTOP or LAYER_BSTOP
is given as the index to the diameter or shape data member, the resulting value will be calculated
according to the Design Rules. If LAYER_VIAS is given, the raw value as defined in the via will
be returned.
<p>
Note that <tt>diameter</tt> and <tt>shape</tt> will always return the diameter or
shape that a via would have in the given layer, even if that particular via doesn't
cover that layer (or if that layer isn't used in the layer setup at all).
<p>
<tt>start</tt> and <tt>end</tt> return the layer numbers in which that via starts and
ends. The value of <tt>start</tt> will always be less than that of <tt>end</tt>.
<p>
<tt>drillsymbol</tt> returns the number of the drill symbol that has been assigned
to this drill diameter (see the manual for a list of defined drill symbols).
A value of <tt>0</tt> means that no symbol has been assigned to this drill diameter.
<h2>Example</h2>
<pre>
board(B) {
B.signals(S) {
S.vias(V) {
printf("Via: (%d %d)\n", V.x, V.y);
}
}
}
</pre>
<a name=209>
<h1>UL_WIRE</h1>
<dl>
<dt>
<b>Data members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>arc</tt> </td><td width=20><td><a href=#172>UL_ARC</a></td></tr>
<tr><td><tt>cap</tt> </td><td width=20><td><a href=#166>int</a> (<tt>CAP_...</tt>)</td></tr>
<tr><td><tt>curve</tt> </td><td width=20><td><a href=#167>real</a></td></tr>
<tr><td><tt>layer</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>style</tt> </td><td width=20><td><a href=#166>int</a> (<tt>WIRE_STYLE_...</tt>)</td></tr>
<tr><td><tt>width</tt> </td><td width=20><td><a href=#166>int</a></td></tr>
<tr><td><tt>x1, y1</tt> </td><td width=20><td><a href=#166>int</a> (starting point)</td></tr>
<tr><td><tt>x2, y2</tt> </td><td width=20><td><a href=#166>int</a> (end point)</td></tr>
</table>
<dt>
<b>Loop members</b>
<dd>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>pieces()</tt> </td><td width=20><td><a href=#209>UL_WIRE</a> (see note)</td></tr>
</table>
</dl>
<b>See also</b> <a href=#175>UL_BOARD</a>,
<a href=#194>UL_PACKAGE</a>,
<a href=#202>UL_SEGMENT</a>,
<a href=#203>UL_SHEET</a>,
<a href=#204>UL_SIGNAL</a>,
<a href=#206>UL_SYMBOL</a>,
<a href=#172>UL_ARC</a>
<h2>Constants</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>CAP_FLAT</tt> </td><td width=20><td>flat arc ends</td></tr>
<tr><td><tt>CAP_ROUND</tt> </td><td width=20><td>round arc ends</td></tr>
<tr><td><tt>WIRE_STYLE_CONTINUOUS</tt> </td><td width=20><td>continuous</td></tr>
<tr><td><tt>WIRE_STYLE_LONGDASH</tt> </td><td width=20><td>long dash</td></tr>
<tr><td><tt>WIRE_STYLE_SHORTDASH</tt> </td><td width=20><td>short dash</td></tr>
<tr><td><tt>WIRE_STYLE_DASHDOT</tt> </td><td width=20><td>dash dot</td></tr>
</table>
<h2>Wire Style</h2>
A UL_WIRE that has a <i>style</i> other than <tt>WIRE_STYLE_CONTINUOUS</tt> can use the
<tt>pieces()</tt> loop member to access the individual segments that constitute
for example a dashed wire. If <tt>pieces()</tt> is called for a UL_WIRE with
<tt>WIRE_STYLE_CONTINUOUS</tt>, a single segment will be accessible which is just
the same as the original UL_WIRE. The <tt>pieces()</tt> loop member can't be called
from a UL_WIRE that itself has been returned by a call to <tt>pieces()</tt> (this would
cause an infinite recursion).
<h2>Arcs at Wire level</h2>
Arcs are basically wires, with a few additional properties. At the first level
arcs are treated exactly the same as wires, meaning they have a start and an end point,
a width, layer and wire style. In addition to these an arc, at the wire level, has
a <i>cap</i> and a <i>curve</i> parameter. <i>cap</i> defines whether the arc endings
are round or flat, and <i>curve</i> defines the "curvature" of the arc. The valid
range for <i>curve</i> is <tt>-360</tt>..<tt>+360</tt>, and its value means what part of
a full circle the arc consists of. A value of <tt>90</tt>, for instance, would
result in a <tt>90&deg;</tt> arc, while <tt>180</tt> would give you a semicircle.
The maximum value of <tt>360</tt> can only be reached theoretically, since this would
mean that the arc consists of a full circle, which, because the start and end points
have to lie on the circle, would have to have an infinitely large diameter.
Positive values for <i>curve</i> mean that the arc is drawn in a mathematically positive
sense (i.e. counterclockwise). If <i>curve</i> is <tt>0</tt>, the arc is a straight
line ("no curvature"), which is actually a wire.
<p>
The <i>cap</i> parameter only has a meaning for actual arcs, and will always return
<tt>CAP_ROUND</tt> for a straight wire.
<p>
Whether or not an UL_WIRE is an arc can be determined by checking the boolean return
value of the <tt>arc</tt> data member. If it returns <tt>0</tt>, we have a straight
wire, otherwise an arc. If <tt>arc</tt> returns a non-zero value it may be further
dereferenced to access the <a href=#172>UL_ARC</a> specific parameters start
and end angle, radius and center point. Note that you may only need these additional
parameters if you are going to draw the arc or process it in other ways where the
actual shape is important.
<h2>Example</h2>
<pre>
board(B) {
B.wires(W) {
printf("Wire: (%d %d) (%d %d)\n",
W.x1, W.y1, W.x2, W.y2);
}
}
</pre>
<a name=210>
<h1>Definitions</h1>
The data items to be used in a User Language Program must be defined
before they can be used.
<p>
There are three kinds of definitions:
<ul>
<li><a href=#211>Constant Definitions</a>
<li><a href=#212>Variable Definitions</a>
<li><a href=#213>Function Definitions</a>
</ul>
The scope of a <i>constant</i> or <i>variable</i> definition
goes from the line in which it has been defined to the end of the current
<a href=#229>block</a>, or to the end of the User
Language Program, if the definition appeared outside any block.
<p>
The scope of a <i>function</i> definition goes from the closing
brace (<tt>}</tt>) of the function body to the end of the User Language
Program.
<a name=211>
<h1>Constant Definitions</h1>
<i>Constants</i> are defined using the keyword <tt>enum</tt>, as in
<pre>
enum { a, b, c };
</pre>
which would define the three constants <tt>a</tt>, <tt>b</tt> and <tt>c</tt>,
giving them the values <tt>0</tt>, <tt>1</tt> and <tt>2</tt>, respectively.
<p>
Constants may also be initialized to specific values, like
<pre>
enum { a, b = 5, c };
</pre>
where <tt>a</tt> would be <tt>0</tt>, <tt>b</tt> would be <tt>5</tt> and
<tt>c</tt> would be <tt>6</tt>.
<a name=212>
<h1>Variable Definitions</h1>
The general syntax of a <i>variable definition</i> is
<pre>
[numeric] type identifier [= initializer][, ...];
</pre>
where <tt>type</tt> is one of the
<a href=#164>data</a> or
<a href=#171>object types</a>,
<tt>identifier</tt> is the name of the variable, and <tt>initializer</tt>
is a optional initial value.
<p>
Multiple variable definitions of the same <tt>type</tt> are separated
by commas (<tt>,</tt>).
<p>
If <tt>identifier</tt> is followed by a pair of
<a href=#157>brackets</a> (<tt>[]</tt>), this defines an array
of variables of the given <tt>type</tt>. The size of an array is
automatically adjusted at runtime.
<p>
The optional keyword <tt>numeric</tt> can be used with
<a href=#168>string</a> arrays to have them sorted
alphanumerically by the <a href=#264>sort()</a> function.
<p>
By default (if no <tt>initializer</tt> is present),
<a href=#164>data variables</a> are set to <tt>0</tt>
(or <tt>""</tt>, in case of a string), and
<a href=#171>object variables</a> are "invalid".
<h2>Examples</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>int i;</tt> </td><td width=20><td>defines an <a href=#166>int</a> variable named <tt>i</tt></td></tr>
<tr><td><tt>string s = "Hello";</tt> </td><td width=20><td>defines a <a href=#168>string</a> variable named <tt>s</tt> and initializes it to <tt>"Hello"</tt></td></tr>
<tr><td><tt>real a, b = 1.0, c;</tt> </td><td width=20><td>defines three <a href=#167>real</a> variables named <tt>a</tt>, <tt>b</tt> and <tt>c</tt>, initializing <tt>b</tt> to the value <tt>1.0</tt></td></tr>
<tr><td><tt>int n[] = { 1, 2, 3 };</tt> </td><td width=20><td>defines an array of <a href=#166>int</a>, initializing the first three elements to <tt>1</tt>, <tt>2</tt> and <tt>3</tt></td></tr>
<tr><td><tt>numeric string names[];</tt> </td><td width=20><td>defines a <a href=#168>string</a> array that can be sorted alphanumerically</td></tr>
<tr><td><tt>UL_WIRE w;</tt> </td><td width=20><td>defines a <a href=#209>UL_WIRE</a> object named <tt>w</tt></td></tr>
</table>
The members of array elements of <a href=#171>object types</a> can't be accessed directly:
<pre>
UL_SIGNAL signals[];
...
UL_SIGNAL s = signals[0];
printf("%s", s.name);
</pre>
<a name=213>
<h1>Function Definitions</h1>
You can write your own User Language functions and call them just like the
<a href=#243>Builtin Functions</a>.
<p>
The general syntax of a <i>function definition</i> is
<pre>
type identifier(parameters)
{
statements
}
</pre>
where <tt>type</tt> is one of the
<a href=#164>data</a> or
<a href=#171>object types</a>,
<tt>identifier</tt> is the name of the function,
<tt>parameters</tt> is a list of comma separated parameter definitions,
and <tt>statements</tt> is a sequence of <a href=#228>statements</a>.
<p>
Functions that do not return a value have the type <tt>void</tt>.
<p>
A function must be defined <b>before</b> it can be called, and function
calls can not be recursive (a function cannot call itself).
<p>
The statements in the function body may modify the values of the parameters,
but this will not have any effect on the arguments of the
<a href=#227>function call</a>.
<p>
Execution of a function can be terminated by the
<tt><a href=#237>return</a></tt> statement. Without any
<tt>return</tt> statement the function body is executed until it's closing
brace (<tt>}</tt>).
<p>
A call to the <tt><a href=#260>exit()</a></tt> function will
terminate the entire User Language Program.
<h2>The special function <tt>main()</tt></h2>
If your User Language Program contains a function called
<tt>main()</tt>, that function will be explicitly called as the
main function, and it's return value will be the
<a href=#140>return value</a> of the program.
<p>
Command line arguments are available to the program through the global
<a href=#242>Builtin Variables</a> <tt>argc</tt> and <tt>argv</tt>.
<h2>Example</h2>
<pre>
int CountDots(string s)
{
int dots = 0;
for (int i = 0; s[i]; ++i)
if (s[i] == '.')
++dots;
return dots;
}
string dotted = "This.has.dots...";
output("test") {
printf("Number of dots: %d\n",
CountDots(dotted));
}
</pre>
<a name=214>
<h1>Operators</h1>
The following table lists all of the User Language operators, in order
of their precedence (<i>Unary</i> having the highest precedence,
<i>Comma</i> the lowest):
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Unary </td><td width=20><td><tt><a href=#216>!</a> <a href=#215>~</a> <a href=#219>+ - ++ --</a></tt></td></tr>
<tr><td>Multiplicative </td><td width=20><td><tt><a href=#219>* / %</a></tt></td></tr>
<tr><td>Additive </td><td width=20><td><tt><a href=#219>+ -</a></tt></td></tr>
<tr><td>Shift </td><td width=20><td><tt><a href=#215>&lt;&lt; &gt;&gt;</a></tt></td></tr>
<tr><td>Relational </td><td width=20><td><tt><a href=#217>&lt; &lt;= &gt; &gt;=</a></tt></td></tr>
<tr><td>Equality </td><td width=20><td><tt><a href=#217>== !=</a></tt></td></tr>
<tr><td>Bitwise AND </td><td width=20><td><tt><a href=#215>&amp;</a></tt></td></tr>
<tr><td>Bitwise XOR </td><td width=20><td><tt><a href=#215>^</a></tt></td></tr>
<tr><td>Bitwise OR </td><td width=20><td><tt><a href=#215>|</a></tt></td></tr>
<tr><td>Logical AND </td><td width=20><td><tt><a href=#216>&amp;&amp;</a></tt></td></tr>
<tr><td>Logical OR </td><td width=20><td><tt><a href=#216>||</a></tt></td></tr>
<tr><td>Conditional </td><td width=20><td><tt><a href=#218>?:</a></tt></td></tr>
<tr><td>Assignment </td><td width=20><td><tt><a href=#219>= *= /= %= += -=</a> <a href=#215>&amp;= ^= |= &lt;&lt;= &gt;&gt;=</a></tt></td></tr>
<tr><td>Comma </td><td width=20><td><tt><a href=#218>,</a></tt></td></tr>
</table>
<p>
Associativity is <b>left to right</b> for all operators, except for
<i>Unary</i>, <i>Conditional</i> and <i>Assignment</i>,
which are <b>right to left</b> associative.
<p>
The normal operator precedence can be altered by the use of
<a href=#158>parentheses</a>.
<a name=215>
<h1>Bitwise Operators</h1>
Bitwise operators work only with data types
<tt><a href=#165>char</a></tt> and
<tt><a href=#166>int</a></tt>.
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><b>Unary</b> </td><td width=20><td></td></tr>
<tr><td><tt>~</tt> </td><td width=20><td>Bitwise (1's) complement</td></tr>
<tr><td><b>Binary</b> </td><td width=20><td></td></tr>
<tr><td><tt>&lt;&lt;</tt> </td><td width=20><td>Shift left</td></tr>
<tr><td><tt>&gt;&gt;</tt> </td><td width=20><td>Shift right</td></tr>
<tr><td><tt>&amp;</tt> </td><td width=20><td>Bitwise AND</td></tr>
<tr><td><tt>^</tt> </td><td width=20><td>Bitwise XOR</td></tr>
<tr><td><tt>|</tt> </td><td width=20><td>Bitwise OR</td></tr>
<tr><td><b>Assignment</b> </td><td width=20><td></td></tr>
<tr><td><tt>&amp;=</tt> </td><td width=20><td>Assign bitwise AND</td></tr>
<tr><td><tt>^=</tt> </td><td width=20><td>Assign bitwise XOR</td></tr>
<tr><td><tt>|=</tt> </td><td width=20><td>Assign bitwise OR</td></tr>
<tr><td><tt>&lt;&lt;=</tt> </td><td width=20><td>Assign left shift</td></tr>
<tr><td><tt>&gt;&gt;=</tt> </td><td width=20><td>Assign right shift</td></tr>
</table>
<a name=216>
<h1>Logical Operators</h1>
Logical operators work with <a href=#221>expressions</a>
of any data type.
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><b>Unary</b> </td><td width=20><td></td></tr>
<tr><td><tt>!</tt> </td><td width=20><td>Logical NOT</td></tr>
<tr><td><b>Binary</b> </td><td width=20><td></td></tr>
<tr><td><tt>&amp;&amp;</tt> </td><td width=20><td>Logical AND</td></tr>
<tr><td><tt>||</tt> </td><td width=20><td>Logical OR</td></tr>
</table>
<p>
Using a <tt><a href=#168>string</a></tt> expression with a
logical operator checks whether the string is empty.
<p>
Using an <a href=#171>Object Type</a> with a logical
operator checks whether that object contains valid data.
<a name=217>
<h1>Comparison Operators</h1>
Comparison operators work with <a href=#221>expressions</a>
of any data type,
except <a href=#171>Object Types</a>.
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>&lt;</tt> </td><td width=20><td>Less than</td></tr>
<tr><td><tt>&lt;=</tt> </td><td width=20><td>Less than or equal to</td></tr>
<tr><td><tt>&gt;</tt> </td><td width=20><td>Greater than</td></tr>
<tr><td><tt>&gt;=</tt> </td><td width=20><td>Greater than or equal to</td></tr>
<tr><td><tt>==</tt> </td><td width=20><td>Equal to</td></tr>
<tr><td><tt>!=</tt> </td><td width=20><td>Not equal to</td></tr>
</table>
<a name=218>
<h1>Evaluation Operators</h1>
Evaluation operators are used to evaluate <a href=#221>expressions</a>
based on a condition, or to group a sequence of expressions and have them
evaluated as one expression.
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>?:</tt> </td><td width=20><td>Conditional</td></tr>
<tr><td><tt>,</tt> </td><td width=20><td>Comma</td></tr>
</table>
<p>
The <i>Conditional</i> operator is used to make a decision within
an expression, as in
<pre>
int a;
// ...code that calculates 'a'
string s = a ? "True" : "False";
</pre>
which is basically the same as
<pre>
int a;
string s;
// ...code that calculates 'a'
if (a)
s = "True";
else
s = "False";
</pre>
but the advantage of the conditional operator is that it can be used in
an expression.
<p>
The <i>Comma</i> operator is used to evaluate a sequence of expressions
from left to right, using the type and value of the right operand as
the result.
<p>
Note that arguments in a function call as well as multiple variable declarations
also use commas as delimiters, but in that case this is <b>not</b> a
comma operator!
<a name=219>
<h1>Arithmetic Operators</h1>
Arithmetic operators work with data types
<tt><a href=#165>char</a></tt>,
<tt><a href=#166>int</a></tt> and
<tt><a href=#167>real</a></tt>
(except for <tt>++</tt>, <tt>--</tt>, <tt>%</tt> and <tt>%=</tt>).
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><b>Unary</b> </td><td width=20><td></td></tr>
<tr><td><tt>+</tt> </td><td width=20><td>Unary plus</td></tr>
<tr><td><tt>-</tt> </td><td width=20><td>Unary minus</td></tr>
<tr><td><tt>++</tt> </td><td width=20><td>Pre- or postincrement</td></tr>
<tr><td><tt>--</tt> </td><td width=20><td>Pre- or postdecrement</td></tr>
<tr><td><b>Binary</b> </td><td width=20><td></td></tr>
<tr><td><tt>*</tt> </td><td width=20><td>Multiply</td></tr>
<tr><td><tt>/</tt> </td><td width=20><td>Divide</td></tr>
<tr><td><tt>%</tt> </td><td width=20><td>Remainder (modulus)</td></tr>
<tr><td><tt>+</tt> </td><td width=20><td>Binary plus</td></tr>
<tr><td><tt>-</tt> </td><td width=20><td>Binary minus</td></tr>
<tr><td><b>Assignment</b> </td><td width=20><td></td></tr>
<tr><td><tt>=</tt> </td><td width=20><td>Simple assignment</td></tr>
<tr><td><tt>*=</tt> </td><td width=20><td>Assign product</td></tr>
<tr><td><tt>/=</tt> </td><td width=20><td>Assign quotient</td></tr>
<tr><td><tt>%=</tt> </td><td width=20><td>Assign remainder (modulus)</td></tr>
<tr><td><tt>+=</tt> </td><td width=20><td>Assign sum</td></tr>
<tr><td><tt>-=</tt> </td><td width=20><td>Assign difference</td></tr>
</table>
<p>
<b>See also</b> <a href=#220>String Operators</a>
<a name=220>
<h1>String Operators</h1>
String operators work with data types
<tt><a href=#165>char</a></tt>,
<tt><a href=#166>int</a></tt> and
<tt><a href=#168>string</a></tt>.
The left operand must always be of type
<tt><a href=#168>string</a></tt>.
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><b>Binary</b> </td><td width=20><td></td></tr>
<tr><td><tt>+</tt> </td><td width=20><td>Concatenation</td></tr>
<tr><td><b>Assignment</b> </td><td width=20><td></td></tr>
<tr><td><tt>=</tt> </td><td width=20><td>Simple assignment</td></tr>
<tr><td><tt>+=</tt> </td><td width=20><td>Append to string</td></tr>
</table>
<p>
The <tt>+</tt> operator concatenates two strings, or adds a character
to the end of a string and returns the resulting string.
<p>
The <tt>+=</tt> operator appends a string or a character to the end of
a given string.
<p>
<b>See also</b> <a href=#219>Arithmetic Operators</a>
<a name=221>
<h1>Expressions</h1>
An <i>expression</i> can be one of the following:
<ul>
<li><a href=#222>Arithmetic Expression</a>
<li><a href=#223>Assignment Expression</a>
<li><a href=#224>String Expression</a>
<li><a href=#225>Comma Expression</a>
<li><a href=#226>Conditional Expression</a>
<li><a href=#227>Function Call</a>
</ul>
Expressions can be grouped using <a href=#158>parentheses</a>,
and may be recursive, meaning that an expression can consist of
subexpressions.
<a name=222>
<h1>Arithmetic Expression</h1>
An <i>arithmetic expression</i> is any combination of numeric
operands and an <a href=#219>arithmetic operator</a> or a
<a href=#215>bitwise operator</a>.
<h2>Examples</h2>
<pre>
a + b
c++
m &lt;&lt; 1
</pre>
<a name=223>
<h1>Assignment Expression</h1>
An <i>assignment expression</i> consists of a variable on the left
side of an <a href=#219>assignment operator</a>, and an
expression on the right side.
<h2>Examples</h2>
<pre>
a = x + 42
b += c
s = "Hello"
</pre>
<a name=224>
<h1>String Expression</h1>
A <i>string expression</i> is any combination of
<a href=#168>string</a> and <a href=#165>char</a>
operands and a <a href=#220>string operator</a>.
<h2>Examples</h2>
<pre>
s + ".brd"
t + 'x'
</pre>
<a name=225>
<h1>Comma Expression</h1>
A <i>comma expression</i> is a sequence of expressions, delimited by
the <a href=#218>comma operator</a>
<p>
Comma expressions are evaluated left to right, and the result of a comma
expression is the type and value of the rightmost expression.
<h2>Example</h2>
<pre>
i++, j++, k++
</pre>
<a name=226>
<h1>Conditional Expression</h1>
A <i>conditional expression</i> uses the
<a href=#218>conditional operator</a> to make a decision
within an expression.
<h2>Example</h2>
<pre>
int a;
// ...code that calculates 'a'
string s = a ? "True" : "False";
</pre>
<a name=227>
<h1>Function Call</h1>
A <i>function call</i> transfers the program flow to a
<a href=#213>user defined function</a> or a
<a href=#243>builtin function</a>.
The formal parameters defined in the
<a href=#213>function definition</a> are replaced
with the values of the expressions used as the actual arguments of the
function call.
<h2>Example</h2>
<pre>
int p = strchr(s, 'b');
</pre>
<a name=228>
<h1>Statements</h1>
A <i>statement</i> can be one of the following:
<ul>
<li><a href=#229>Compound Statement</a>
<li><a href=#231>Control Statement</a>
<li><a href=#230>Expression Statement</a>
<li><a href=#293>Builtin Statement</a>
<li><a href=#211>Constant Definition</a>
<li><a href=#212>Variable Definition</a>
</ul>
Statements specify the flow of control as a User Language Program
executes. In absence of specific control statements, statements are
executed sequentially in the order of appearance in the ULP file.
<a name=229>
<h1>Compound Statement</h1>
A <i>compound statement</i> (also known as <i>block</i>) is a list
(possibly empty) of statements enclosed in matching braces (<tt>{}</tt>).
Syntactically, a block can be considered to be a single statement, but it
also controls the scoping of identifiers. An
<a href=#149>identifier</a> declared within a block has a
scope starting at the point of declaration and ending at the closing
brace.
<p>
Compound statements can be nested to any depth.
<a name=230>
<h1>Expression Statement</h1>
An <i>expression statement</i> is any
<a href=#221>expression</a> followed by a
<a href=#161>semicolon</a>.
<p>
An expression statement is executed by evaluating the expression.
All side effects of this evaluation are completed before the next
<a href=#228>statement</a> is executed.
Most expression statements are
<a href=#223>assignments</a> or
<a href=#227>function calls</a>.
<p>
A special case is the <i>empty statement</i>, consisting of only a
<a href=#161>semicolon</a>.
An empty statement does nothing, but it may be useful in situations
where the ULP syntax expects a statement but your program does not
need one.
<a name=231>
<h1>Control Statements</h1>
<i>Control statements</i> are used to control the program flow.
<p>
Iteration statements are
<pre>
<a href=#234>do...while</a>
<a href=#235>for</a>
<a href=#239>while</a>
</pre>
Selection statements are
<pre>
<a href=#236>if...else</a>
<a href=#238>switch</a>
</pre>
Jump statements are
<pre>
<a href=#232>break</a>
<a href=#233>continue</a>
<a href=#237>return</a>
</pre>
<a name=232>
<h1>break</h1>
The <i>break</i> statement has the general syntax
<pre>
break;
</pre>
and immediately terminates the <b>nearest</b> enclosing
<a href=#234>do...while</a>,
<a href=#235>for</a>,
<a href=#238>switch</a> or
<a href=#239>while</a>
statement.
This also applies to <i>loop members</i> of <a href=#171>object types</a>.
<p>
Since all of these statements can be intermixed and nested to any
depth, take care to ensure that your <tt>break</tt> exits from the
correct statement.
<a name=233>
<h1>continue</h1>
The <i>continue</i> statement has the general syntax
<pre>
continue;
</pre>
and immediately transfers control to the test condition of the
<b>nearest</b> enclosing
<a href=#234>do...while</a>,
<a href=#239>while</a>, or
<a href=#235>for</a> statement, or to the increment expression
of the <b>nearest</b> enclosing
<a href=#239>for</a>
statement.
<p>
Since all of these statements can be intermixed and nested to any
depth, take care to ensure that your <tt>continue</tt> affects the
correct statement.
<a name=234>
<h1>do...while</h1>
The <i>do...while</i> statement has the general syntax
<pre>
do statement while (condition);
</pre>
and executes the <tt>statement</tt> until the <tt>condition</tt>
expression becomes zero.
<p>
The <tt>condition</tt> is tested <b>after</b> the first
execution of <tt>statement</tt>, which means that the statement is
always executed at least one time.
<p>
If there is no
<tt><a href=#232>break</a></tt> or
<tt><a href=#237>return</a></tt>
inside the <tt>statement</tt>, the <tt>statement</tt> must affect
the value of the <tt>condition</tt>, or <tt>condition</tt> itself must
change during evaluation in order to avoid an endless loop.
<h2>Example</h2>
<pre>
string s = "Trust no one!";
int i = -1;
do {
++i;
} while (s[i]);
</pre>
<a name=235>
<h1>for</h1>
The <i>for</i> statement has the general syntax
<pre>
for ([init]; [test]; [inc]) statement
</pre>
and performs the following steps:
<ol>
<li>If an initializing expression <tt>init</tt> is present, it is executed.
<li>If a <tt>test</tt> expression is present, it is executed. If the result
is nonzero (or if there is no <tt>test</tt> expression at all), the
<tt>statement</tt> is executed.
<li>If an <tt>inc</tt> expression is present, it is executed.
<li>Finally control returns to step 2.
</ol>
If there is no
<tt><a href=#232>break</a></tt> or
<tt><a href=#237>return</a></tt>
inside the <tt>statement</tt>, the <tt>inc</tt> expression (or the
<tt>statement</tt>) must affect
the value of the <tt>test</tt> expression, or <tt>test</tt> itself must
change during evaluation in order to avoid an endless loop.
<p>
The initializing expression <tt>init</tt> normally initializes one or more
loop counters. It may also define a new variable as a loop counter.
The scope of such a variable is valid until the end of the active block.
<h2>Example</h2>
<pre>
string s = "Trust no one!";
int sum = 0;
for (int i = 0; s[i]; ++i)
sum += s[i]; // sums up the characters in s
</pre>
<a name=236>
<h1>if...else</h1>
The <i>if...else</i> statement has the general syntax
<pre>
if (expression)
t_statement
[else
f_statement]
</pre>
The conditional <tt>expression</tt> is evaluated, and if its value is nonzero
the <tt>t_statement</tt> is executed. Otherwise the <tt>f_statement</tt> is
executed in case there is an <tt>else</tt> clause.
<p>
An <tt>else</tt> clause is always matched to the last encountered <tt>if</tt>
without an <tt>else</tt>. If this is not what you want, you need to use
<a href=#159>braces</a> to group the statements, as in
<pre>
if (a == 1) {
if (b == 1)
printf("a == 1 and b == 1\n");
}
else
printf("a != 1\n");
</pre>
<a name=237>
<h1>return</h1>
A <a href=#213>function</a> with a return type
other than <tt>void</tt> must contain at least one <i>return</i>
statement with the syntax
<pre>
return expression;
</pre>
where <tt>expression</tt> must evaluate to a type that is compatible with
the function's return type. The value of <tt>expression</tt> is the value
returned by the function.
<p>
If the function is of type <tt>void</tt>, a <tt>return</tt> statement
without an <tt>expression</tt> can be used to return from the function
call.
<a name=238>
<h1>switch</h1>
The <i>switch</i> statement has the general syntax
<pre>
switch (sw_exp) {
case case_exp: case_statement
...
[default: def_statement]
}
</pre>
and allows for the transfer of control to one of several
<tt>case</tt>-labeled statements, depending on the value of
<tt>sw_exp</tt> (which must be of integral type).
<p>
Any <tt>case_statement</tt> can be labeled by one or more <tt>case</tt>
labels. The <tt>case_exp</tt> of each <tt>case</tt> label must evaluate
to a constant integer which is unique within it's enclosing <tt>switch</tt>
statement.
<p>
There can also be at most one <tt>default</tt> label.
<p>
After evaluating <tt>sw_exp</tt>, the <tt>case_exp</tt> are checked for
a match. If a match is found, control passes to the <tt>case_statement</tt>
with the matching <tt>case</tt> label.
<p>
If no match is found and there is a <tt>default</tt> label, control
passes to <tt>def_statement</tt>. Otherwise none of the statements in the
<tt>switch</tt> is executed.
<p>
Program execution is not affected when <tt>case</tt> and <tt>default</tt>
labels are encountered. Control simply passes through the labels to the
following statement.
<p>
To stop execution at the end of a group of statements for a particular
<tt>case</tt>, use the <a href=#232>break</a> statement.
<h2>Example</h2>
<pre>
string s = "Hello World";
int vowels = 0, others = 0;
for (int i = 0; s[i]; ++i)
switch (toupper(s[i])) {
case 'A':
case 'E':
case 'I':
case 'O':
case 'U': ++vowels;
break;
default: ++others;
}
printf("There are %d vowels in '%s'\n", vowels, s);
</pre>
<a name=239>
<h1>while</h1>
The <i>while</i> statement has the general syntax
<pre>
while (condition) statement
</pre>
and executes the <tt>statement</tt> as long as the <tt>condition</tt>
expression is not zero.
<p>
The <tt>condition</tt> is tested <b>before</b> the first possible
execution of <tt>statement</tt>, which means that the statement may never
be executed if <tt>condition</tt> is initially zero.
<p>
If there is no
<tt><a href=#232>break</a></tt> or
<tt><a href=#237>return</a></tt>
inside the <tt>statement</tt>, the <tt>statement</tt> must affect
the value of the <tt>condition</tt>, or <tt>condition</tt> itself must
change during evaluation in order to avoid an endless loop.
<h2>Example</h2>
<pre>
string s = "Trust no one!";
int i = 0;
while (s[i])
++i;
</pre>
<a name=240>
<h1>Builtins</h1>
Builtins are <i>Constants</i>, <i>Variables</i>, <i>Functions</i> and <i>Statements</i>
that provide additional information and allow for data manipulations.
<ul>
<li><a href=#241>Builtin Constants</a>
<li><a href=#242>Builtin Variables</a>
<li><a href=#243>Builtin Functions</a>
<li><a href=#293>Builtin Statements</a>
</ul>
<a name=241>
<h1>Builtin Constants</h1>
<i>Builtin constants</i> are used to provide information about
object parameters, such as maximum recommended name length, flags etc.
<p>
Many of the <a href=#171>object types</a> have their
own <b>Constants</b> section which lists the builtin constants for that
particular object (see e.g. <a href=#197>UL_PIN</a>).
<p>
The following builtin constants are defined in addition to the ones
listed for the various object types:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>EAGLE_VERSION</tt> </td><td width=20><td>EAGLE program version number (<a href=#166>int</a>)</td></tr>
<tr><td><tt>EAGLE_RELEASE</tt> </td><td width=20><td>EAGLE program release number (<a href=#166>int</a>)</td></tr>
<tr><td><tt>EAGLE_SIGNATURE</tt> </td><td width=20><td>a <a href=#168>string</a> containing EAGLE program name, version and copyright information</td></tr>
<tr><td><tt>REAL_EPSILON</tt> </td><td width=20><td>the minimum positive <a href=#167>real</a> number such that <tt>1.0 + REAL_EPSILON != 1.0</tt></td></tr>
<tr><td><tt>REAL_MAX</tt> </td><td width=20><td>the largest possible <a href=#167>real</a> value</td></tr>
<tr><td><tt>REAL_MIN</tt> </td><td width=20><td>the smallest possible (positive!) <a href=#167>real</a> value<br>the smallest representable number is <tt>-REAL_MAX</tt></td></tr>
<tr><td><tt>INT_MAX</tt> </td><td width=20><td>the largest possible <a href=#166>int</a> value</td></tr>
<tr><td><tt>INT_MIN</tt> </td><td width=20><td>the smallest possible <a href=#166>int</a> value</td></tr>
<tr><td><tt>PI</tt> </td><td width=20><td>the value of "pi" (3.14..., <a href=#167>real</a>)</td></tr>
<tr><td><tt>usage</tt> </td><td width=20><td>a <a href=#168>string</a> containing the text from the <tt><a href=#147>#usage</a></tt> directive</td></tr>
</table>
<p>
These builtin constants contain the directory paths defined in the
<a href=#14>directories dialog</a>, with any of the special
variables (<tt>$HOME</tt> and <tt>$EAGLEDIR</tt>) replaced by their actual values.
Since each path can consist of several directories, these constants are <a href=#168>string</a>
arrays with an individual directory in each member. The first empty member marks the end of the path:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>path_lbr[]</tt> </td><td width=20><td>Libraries</td></tr>
<tr><td><tt>path_dru[]</tt> </td><td width=20><td>Design Rules</td></tr>
<tr><td><tt>path_ulp[]</tt> </td><td width=20><td>User Language Programs</td></tr>
<tr><td><tt>path_scr[]</tt> </td><td width=20><td>Scripts</td></tr>
<tr><td><tt>path_cam[]</tt> </td><td width=20><td>CAM Jobs</td></tr>
<tr><td><tt>path_epf[]</tt> </td><td width=20><td>Projects</td></tr>
</table>
<p>
When using these constants to build a full file name, you need to use a directory separator,
as in
<pre>
string s = path_lbr[0] + '/' + "mylib.lbr";
</pre>
<p>
The libraries that are currently in use through the <a href=#102>USE</a> command:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>used_libraries[]</tt> </td><td width=20><td></td></tr>
</table>
<a name=242>
<h1>Builtin Variables</h1>
<i>Builtin variables</i> are used to provide information at runtime.
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>int argc</tt> </td><td width=20><td>number of arguments given to the <a href=#90>RUN</a> command</td></tr>
<tr><td><tt>string argv[]</tt> </td><td width=20><td>arguments given to the RUN command (<tt>argv[0]</tt> is the full ULP file name)</td></tr>
</table>
<a name=243>
<h1>Builtin Functions</h1>
<i>Builtin functions</i> are used to perform specific tasks, like
printing formatted strings, sorting data arrays or the like.
<p>
You may also write your own <a href=#213>functions</a>
and use them to structure your User Language Program.
<p>
The builtin functions are grouped into the following categories:
<ul>
<li><a href=#244>Character Functions</a>
<li><a href=#247>File Handling Functions</a>
<li><a href=#254>Mathematical Functions</a>
<li><a href=#259>Miscellaneous Functions</a>
<li><a href=#268>Printing Functions</a>
<li><a href=#271>String Functions</a>
<li><a href=#285>Time Functions</a>
<li><a href=#289>Object Functions</a>
</ul>
Alphabetical reference of all builtin functions:
<ul>
<li><a href=#255>abs()</a>
<li><a href=#257>acos()</a>
<li><a href=#257>asin()</a>
<li><a href=#257>atan()</a>
<li><a href=#256>ceil()</a>
<li><a href=#290>clrgroup()</a>
<li><a href=#257>cos()</a>
<li><a href=#260>exit()</a>
<li><a href=#258>exp()</a>
<li><a href=#250>filedir()</a>
<li><a href=#248>fileerror()</a>
<li><a href=#250>fileext()</a>
<li><a href=#249>fileglob()</a>
<li><a href=#250>filename()</a>
<li><a href=#253>fileread()</a>
<li><a href=#250>filesetext()</a>
<li><a href=#251>filesize()</a>
<li><a href=#251>filetime()</a>
<li><a href=#256>floor()</a>
<li><a href=#256>frac()</a>
<li><a href=#291>ingroup()</a>
<li><a href=#245>isalnum()</a>
<li><a href=#245>isalpha()</a>
<li><a href=#245>iscntrl()</a>
<li><a href=#245>isdigit()</a>
<li><a href=#245>isgraph()</a>
<li><a href=#245>islower()</a>
<li><a href=#245>isprint()</a>
<li><a href=#245>ispunct()</a>
<li><a href=#245>isspace()</a>
<li><a href=#245>isupper()</a>
<li><a href=#245>isxdigit()</a>
<li><a href=#261>language()</a>
<li><a href=#258>log()</a>
<li><a href=#258>log10()</a>
<li><a href=#262>lookup()</a>
<li><a href=#255>max()</a>
<li><a href=#255>min()</a>
<li><a href=#263>palette()</a>
<li><a href=#258>pow()</a>
<li><a href=#269>printf()</a>
<li><a href=#256>round()</a>
<li><a href=#292>setgroup()</a>
<li><a href=#257>sin()</a>
<li><a href=#264>sort()</a>
<li><a href=#270>sprintf()</a>
<li><a href=#258>sqrt()</a>
<li><a href=#265>status()</a>
<li><a href=#272>strchr()</a>
<li><a href=#273>strjoin()</a>
<li><a href=#274>strlen()</a>
<li><a href=#275>strlwr()</a>
<li><a href=#276>strrchr()</a>
<li><a href=#277>strrstr()</a>
<li><a href=#278>strsplit()</a>
<li><a href=#279>strstr()</a>
<li><a href=#280>strsub()</a>
<li><a href=#281>strtod()</a>
<li><a href=#282>strtol()</a>
<li><a href=#283>strupr()</a>
<li><a href=#284>strxstr()</a>
<li><a href=#266>system()</a>
<li><a href=#288>t2day()</a>
<li><a href=#288>t2dayofweek()</a>
<li><a href=#288>t2hour()</a>
<li><a href=#288>t2minute()</a>
<li><a href=#288>t2month()</a>
<li><a href=#288>t2second()</a>
<li><a href=#288>t2string()</a>
<li><a href=#288>t2year()</a>
<li><a href=#257>tan()</a>
<li><a href=#286>time()</a>
<li><a href=#246>tolower()</a>
<li><a href=#246>toupper()</a>
<li><a href=#256>trunc()</a>
<li><a href=#267>u2inch()</a>
<li><a href=#267>u2mic()</a>
<li><a href=#267>u2mil()</a>
<li><a href=#267>u2mm()</a>
</ul>
<a name=244>
<h1>Character Functions</h1>
<i>Character functions</i> are used to manipulate single characters.
<p>
The following character functions are available:
<ul>
<li><a href=#245>isalnum()</a>
<li><a href=#245>isalpha()</a>
<li><a href=#245>iscntrl()</a>
<li><a href=#245>isdigit()</a>
<li><a href=#245>isgraph()</a>
<li><a href=#245>islower()</a>
<li><a href=#245>isprint()</a>
<li><a href=#245>ispunct()</a>
<li><a href=#245>isspace()</a>
<li><a href=#245>isupper()</a>
<li><a href=#245>isxdigit()</a>
<li><a href=#246>tolower()</a>
<li><a href=#246>toupper()</a>
</ul>
<a name=245>
<h1>is...()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Check whether a character falls into a given category.
<dt>
<b>Syntax</b>
<dd>
<tt>int isalnum(char c);</tt><br>
<tt>int isalpha(char c);</tt><br>
<tt>int iscntrl(char c);</tt><br>
<tt>int isdigit(char c);</tt><br>
<tt>int isgraph(char c);</tt><br>
<tt>int islower(char c);</tt><br>
<tt>int isprint(char c);</tt><br>
<tt>int ispunct(char c);</tt><br>
<tt>int isspace(char c);</tt><br>
<tt>int isupper(char c);</tt><br>
<tt>int isxdigit(char c);</tt>
<dt>
<b>Returns</b>
<dd>
The <tt>is...</tt> functions return nonzero if the given character falls
into the category, zero otherwise.
</dl>
<h2>Character categories</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>isalnum</tt> </td><td width=20><td>letters (<tt>A</tt> to <tt>Z</tt> or <tt>a</tt> to <tt>z</tt>) or digits (<tt>0</tt> to <tt>9</tt>)</td></tr>
<tr><td><tt>isalpha </tt> </td><td width=20><td>letters (<tt>A</tt> to <tt>Z</tt> or <tt>a</tt> to <tt>z</tt>)</td></tr>
<tr><td><tt>iscntrl </tt> </td><td width=20><td>delete characters or ordinary control characters (<tt>0x7F</tt> or <tt>0x00</tt> to <tt>0x1F</tt>)</td></tr>
<tr><td><tt>isdigit </tt> </td><td width=20><td>digits (<tt>0</tt> to <tt>9</tt>)</td></tr>
<tr><td><tt>isgraph </tt> </td><td width=20><td>printing characters (except space)</td></tr>
<tr><td><tt>islower </tt> </td><td width=20><td>lowercase letters (<tt>a</tt> to <tt>z</tt>)</td></tr>
<tr><td><tt>isprint </tt> </td><td width=20><td>printing characters (<tt>0x20</tt> to <tt>0x7E</tt>)</td></tr>
<tr><td><tt>ispunct </tt> </td><td width=20><td>punctuation characters (<tt>iscntrl</tt> or <tt>isspace</tt>)</td></tr>
<tr><td><tt>isspace </tt> </td><td width=20><td>space, tab, carriage return, new line, vertical tab, or formfeed (<tt>0x09</tt> to <tt>0x0D</tt>, <tt>0x20</tt>)</td></tr>
<tr><td><tt>isupper </tt> </td><td width=20><td>uppercase letters (<tt>A</tt> to <tt>Z</tt>)</td></tr>
<tr><td><tt>isxdigit</tt> </td><td width=20><td>hex digits (<tt>0</tt> to <tt>9</tt>, <tt>A</tt> to <tt>F</tt>, <tt>a</tt> to <tt>f</tt>)</td></tr>
</table>
<h2>Example</h2>
<pre>
char c = 'A';
if (isxdigit(c))
printf("%c is hex\n", c);
else
printf("%c is not hex\n", c);
</pre>
<a name=246>
<h1>to...()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Convert a character to upper- or lowercase.
<dt>
<b>Syntax</b>
<dd>
<tt>char tolower(char c);</tt><br>
<tt>char toupper(char c);</tt>
<dt>
<b>Returns</b>
<dd>
The <tt>tolower</tt> function returns the converted character if <tt>c</tt>
is uppercase. All other characters are returned unchanged.<br>
The <tt>toupper</tt> function returns the converted character if <tt>c</tt>
is lowercase. All other characters are returned unchanged.
</dl>
<b>See also</b> <a href=#283>strupr</a>,
<a href=#275>strlwr</a>
<a name=247>
<h1>File Handling Functions</h1>
<i>Filename handling functions</i> are used to work with file names,
sizes and timestamps.
<p>
The following file handling functions are available:
<ul>
<li><a href=#248>fileerror()</a>
<li><a href=#249>fileglob()</a>
<li><a href=#250>filedir()</a>
<li><a href=#250>fileext()</a>
<li><a href=#250>filename()</a>
<li><a href=#253>fileread()</a>
<li><a href=#250>filesetext()</a>
<li><a href=#251>filesize()</a>
<li><a href=#251>filetime()</a>
</ul>
See <a href=#297>output()</a> for information about how to write into a file.
<a name=248>
<h1>fileerror()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Returns the status of I/O operations.
<dt>
<b>Syntax</b>
<dd>
<tt>int fileerror();</tt>
<dt>
<b>Returns</b>
<dd>
The <tt>fileerror</tt> function returns <tt>0</tt> if everything is ok.
</dl>
<b>See also</b> <a href=#297>output</a>,
<a href=#269>printf</a>,
<a href=#253>fileread</a>
<p>
<tt>fileerror</tt> checks the status of any I/O operations that have been performed
since the last call to this function and returns <tt>0</tt> if everything was ok.
If any of the I/O operations has caused an error, a value other than <tt>0</tt>
will be returned.
<p>
You should call <tt>fileerror</tt> before any I/O operations to reset any previous
error state, and call it again after the I/O operations to see if they were successful.
<p>
When <tt>fileerror</tt> returns a value other than <tt>0</tt> (thus indicating an error)
a proper error message has already been given to the user.
<h2>Example</h2>
<pre>
fileerror();
output("file.txt", "wt") {
printf("Test\n");
}
if (fileerror())
exit(1);
</pre>
<a name=249>
<h1>fileglob()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Perform a directory search.
<dt>
<b>Syntax</b>
<dd>
<tt>int fileglob(string &amp;array[], string pattern);</tt>
<dt>
<b>Returns</b>
<dd>
The <tt>fileglob</tt> function returns the number of entries copied into <tt>array</tt>.
</dl>
<b>See also</b> <a href=#305>dlgFileOpen()</a>,
<a href=#305>dlgFileSave()</a>
<p>
<tt>fileglob</tt> performs a directory search using <tt>pattern</tt>.
<p>
<tt>pattern</tt> may contain <tt>'*'</tt> and <tt>'?'</tt> as wildcard characters.
If <tt>pattern</tt> ends with a <tt>'/'</tt>, the contents of the given directory will be returned.
<p>
Names in the resulting <tt>array</tt> that end with a <tt>'/'</tt> are directory names.
<p>
The <tt>array</tt> is sorted alphabetically, with the directories coming first.
<p>
The special entries <tt>'.'</tt> and <tt>'..'</tt> (for the current and parent directories)
are never returned in the <tt>array</tt>.
<p>
If <tt>pattern</tt> doesn't match, or if you don't have permission to search the given
directory, the resulting <tt>array</tt> will be empty.
<h2>Note for Windows users</h2>
<table><tr><td valign="top"><img src="platforms-win.png"></td><td valign="middle">
The directory delimiter in the <tt>array</tt> is always a <b>forward slash</b>.
This makes sure User Language Programs will work platform independently.
In the <tt>pattern</tt> the <b>backslash</b> (<tt>'\'</tt>) is also treated
as a directory delimiter.
<p>
Sorting filenames under Windows is done case insensitively.
</td></tr></table>
<h2>Example</h2>
<pre>
string a[];
int n = fileglob(a, "*.brd");
</pre>
<a name=250>
<h1>Filename Functions</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Split a filename into its separate parts.
<dt>
<b>Syntax</b>
<dd>
<tt>string filedir(string file);</tt><br>
<tt>string fileext(string file);</tt><br>
<tt>string filename(string file);</tt><br>
<tt>string filesetext(string file, string newext);</tt>
<dt>
<b>Returns</b>
<dd>
<tt>filedir </tt> returns the directory of <tt>file</tt> (including the drive letter under Windows).<br>
<tt>fileext </tt> returns the extension of <tt>file</tt>.<br>
<tt>filename </tt> returns the file name of <tt>file</tt> (including the extension).<br>
<tt>filesetext</tt> returns <tt>file</tt> with the extension set to <tt>newext</tt>.
</dl>
<b>See also</b> <a href=#251>Filedata Functions</a>
<h2>Example</h2>
<pre>
if (board) board(B) {
output(filesetext(B.name, ".out")) {
...
}
}
</pre>
<a name=251>
<h1>Filedata Functions</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Gets the timestamp and size of a file.
<dt>
<b>Syntax</b>
<dd>
<tt>int filesize(string filename);</tt><br>
<tt>int filetime(string filename);</tt>
<dt>
<b>Returns</b>
<dd>
<tt>filesize</tt> returns the size (in byte) of the given file.<br>
<tt>filetime</tt> returns the timestamp of the given file in a format to be used with the <a href=#285>time functions</a>.
</dl>
<b>See also</b> <a href=#286>time</a>,
<a href=#250>Filename Functions</a>
<h2>Example</h2>
<pre>
board(B)
printf("Board: %s\nSize: %d\nTime: %s\n",
B.name, filesize(B.name),
t2string(filetime(B.name)));
</pre>
<a name=252>
<h1>File Input Functions</h1>
<i>File input functions</i> are used to read data from files.
<p>
The following file input is available:
<ul>
<li><a href=#253>fileread()</a>
</ul>
See <a href=#297>output()</a> for information about how to write into a file.
<a name=253>
<h1>fileread()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Reads data from a file.
<dt>
<b>Syntax</b>
<dd>
<tt>int fileread(<i>dest</i>, string file);</tt>
<dt>
<b>Returns</b>
<dd>
<tt>fileread</tt> returns the number of objects read from the file.<br>
The actual meaning of the return value depends on the type of <tt>dest</tt>.
</dl>
<b>See also</b> <a href=#262>lookup</a>,
<a href=#278>strsplit</a>,
<a href=#248>fileerror</a>
<p>
If <tt>dest</tt> is a character array, the file will be read as raw binary data
and the return value reflects the number of bytes read into the character array
(which is equal to the file size).
<p>
If <tt>dest</tt> is a string array, the file will be read as a text file (one line
per array member) and the return value will be the number of lines read into the
string array. Newline characters will be stripped.
<p>
If <tt>dest</tt> is a string, the entire file will be read into that string
and the return value will be the length of that string (which is not necessarily
equal to the file size, if the operating system stores text files with "cr/lf"
instead of a "newline" character).
<h2>Example</h2>
<pre>
char b[];
int nBytes = fileread(b, "data.bin");
string lines[];
int nLines = fileread(lines, "data.txt");
string text;
int nChars = fileread(text, "data.txt");
</pre>
<a name=254>
<h1>Mathematical Functions</h1>
<i>Mathematical functions</i> are used to perform mathematical
operations.
<p>
The following mathematical functions are available:
<ul>
<li><a href=#255>abs()</a>
<li><a href=#257>acos()</a>
<li><a href=#257>asin()</a>
<li><a href=#257>atan()</a>
<li><a href=#256>ceil()</a>
<li><a href=#257>cos()</a>
<li><a href=#258>exp()</a>
<li><a href=#256>floor()</a>
<li><a href=#256>frac()</a>
<li><a href=#258>log()</a>
<li><a href=#258>log10()</a>
<li><a href=#255>max()</a>
<li><a href=#255>min()</a>
<li><a href=#258>pow()</a>
<li><a href=#256>round()</a>
<li><a href=#257>sin()</a>
<li><a href=#258>sqrt()</a>
<li><a href=#256>trunc()</a>
<li><a href=#257>tan()</a>
</ul>
<h2>Error Messages</h2>
If the arguments of a mathematical function call lead to an error, the
error message will show the actual values of the arguments. Thus the
statements
<pre>
real x = -1.0;
real r = sqrt(2 * x);
</pre>
will lead to the error message
<pre>
Invalid argument in call to 'sqrt(-2)'
</pre>
<a name=255>
<h1>Absolute, Maximum and Minimum Functions</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Absolute, maximum and minimum functions.
<dt>
<b>Syntax</b>
<dd>
<tt>type abs(type x);</tt><br>
<tt>type max(type x, type y);</tt><br>
<tt>type min(type x, type y);</tt>
<dt>
<b>Returns</b>
<dd>
<tt>abs</tt> returns the absolute value of <tt>x</tt>.<br>
<tt>max</tt> returns the maximum of <tt>x</tt> and <tt>y</tt>.<br>
<tt>min</tt> returns the minimum of <tt>x</tt> and <tt>y</tt>.
<p>
The return type of these functions is the same as the (larger) type
of the arguments. <tt>type</tt> must be one of
<tt><a href=#165>char</a></tt>,
<tt><a href=#166>int</a></tt> or
<tt><a href=#167>real</a></tt>.
</dl>
<h2>Example</h2>
<pre>
real x = 2.567, y = 3.14;
printf("The maximum is %f\n", max(x, y));
</pre>
<a name=256>
<h1>Rounding Functions</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Rounding functions.
<dt>
<b>Syntax</b>
<dd>
<tt>real ceil(real x);</tt><br>
<tt>real floor(real x);</tt><br>
<tt>real frac(real x);</tt><br>
<tt>real round(real x);</tt><br>
<tt>real trunc(real x);</tt>
<dt>
<b>Returns</b>
<dd>
<tt>ceil </tt> returns the smallest integer not less than <tt>x</tt>.<br>
<tt>floor</tt> returns the largest integer not greater than <tt>x</tt>.<br>
<tt>frac </tt> returns the fractional part of <tt>x</tt>.<br>
<tt>round</tt> returns <tt>x</tt> rounded to the nearest integer.<br>
<tt>trunc</tt> returns the integer part of <tt>x</tt>.
</dl>
<h2>Example</h2>
<pre>
real x = 2.567;
printf("The rounded value of %f is %f\n", x, round(x));
</pre>
<a name=257>
<h1>Trigonometric Functions</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Trigonometric functions.
<dt>
<b>Syntax</b>
<dd>
<tt>real acos(real x);</tt><br>
<tt>real asin(real x);</tt><br>
<tt>real atan(real x);</tt><br>
<tt>real cos(real x);</tt><br>
<tt>real sin(real x);</tt><br>
<tt>real tan(real x);</tt>
<dt>
<b>Returns</b>
<dd>
<tt>acos</tt> returns the arc cosine of <tt>x</tt>.<br>
<tt>asin</tt> returns the arc sine of <tt>x</tt>.<br>
<tt>atan</tt> returns the arc tangent of <tt>x</tt>.<br>
<tt>cos </tt> returns the cosine of <tt>x</tt>.<br>
<tt>sin </tt> returns the sine of <tt>x</tt>.<br>
<tt>tan </tt> returns the tangent of <tt>x</tt>.
</dl>
<h2>Constants</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>PI</tt> </td><td width=20><td>the value of "pi" (3.14...)</td></tr>
</table>
<h2>Example</h2>
<pre>
real x = PI / 2;
printf("The sine of %f is %f\n", x, sin(x));
</pre>
<a name=258>
<h1>Exponential Functions</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Exponential Functions.
<dt>
<b>Syntax</b>
<dd>
<tt>real exp(real x);</tt><br>
<tt>real log(real x);</tt><br>
<tt>real log10(real x);</tt><br>
<tt>real pow(real x, real y);</tt><br>
<tt>real sqrt(real x);</tt>
<dt>
<b>Returns</b>
<dd>
<tt>exp </tt> returns the exponential <i>e</i> to the power of <tt>x</tt>.<br>
<tt>log </tt> returns the natural logarithm of <tt>x</tt>.<br>
<tt>log10</tt> returns the base 10 logarithm of <tt>x</tt>.<br>
<tt>pow </tt> returns the value of <tt>x</tt> to the power of <tt>y</tt>.<br>
<tt>sqrt </tt> returns the square root of <tt>x</tt>.
</dl>
<h2>Note</h2>
The "n-th" root can be calculated using the <tt>pow</tt> function with a
negative exponent.
<h2>Example</h2>
<pre>
real x = 2.1;
printf("The square root of %f is %f\n", x, sqrt(x));
</pre>
<a name=259>
<h1>Miscellaneous Functions</h1>
<i>Miscellaneous functions</i> are used to perform various tasks.
<p>
The following miscellaneous functions are available:
<ul>
<li><a href=#260>exit()</a>
<li><a href=#261>language()</a>
<li><a href=#262>lookup()</a>
<li><a href=#263>palette()</a>
<li><a href=#264>sort()</a>
<li><a href=#265>status()</a>
<li><a href=#266>system()</a>
<li><a href=#267>Unit Conversions</a>
</ul>
<a name=260>
<h1>exit()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Exits from a User Language Program.
<dt>
<b>Syntax</b>
<dd>
<tt>void exit(int result);</tt><br>
<tt>void exit(string command);</tt>
</dl>
<b>See also</b> <a href=#90>RUN</a>
<p>
The <tt>exit</tt> function terminates execution of a User Language Program.<br>
If an integer <tt>result</tt> is given it will be used as the
<a href=#140>return value</a> of the program.<br>
If a string <tt>command</tt> is given, that command will be executed as if it
were entered into the command line immediately after the RUN command. In that
case the return value of the ULP is set to <tt>EXIT_SUCCESS</tt>.
<h2>Constants</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>EXIT_SUCCESS</tt> </td><td width=20><td>return value for successful program execution (value <tt>0</tt>)</td></tr>
<tr><td><tt>EXIT_FAILURE</tt> </td><td width=20><td>return value for failed program execution (value <tt>-1</tt>)</td></tr>
</table>
<p>
<a name=261>
<h1>language()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Returns the language code of the system in use.
<dt>
<b>Syntax</b>
<dd>
<tt>string language();</tt>
<dt>
<b>Returns</b>
<dd>
<tt>language</tt> returns a string consisting of two lowercase characters
that identifies the language used on the current system.
If no such language setting can be determined, an empty string will
be returned.
</dl>
The <tt>language</tt> function can be used to make a ULP use different
message string, depending on which language the current system is using.
<p>
In the example below all the strings used in the ULP are listed in the
string array <tt>I18N[]</tt>, preceeded by a string containing the
various language codes supported by this ULP. Note the <tt>vtab</tt>
characters used to separate the individual parts of each string (they
are important for the <tt>lookup</tt> function) and the use of the commas
to separate the strings. The actual work is done in the function <tt>tr()</tt>,
which returns the translated version of the given string.
If the original string can't be found in the <tt>I18N</tt> array, or there
is no translation for the current language, the original string will be used
untranslated.
<p>
The first language defined in the <tt>I18N</tt> array must be the one in which
the strings used throughout the ULP are written, and should generally be
English in order to make the program accessible to the largest number of users.
<h2>Example</h2>
<pre>
string I18N[] = {
"en\v"
"de\v"
"it\v"
,
"I18N Demo\v"
"Beispiel f&uuml;r Internationalisierung\v"
"Esempio per internazionalizzazione\v"
,
"Hello world!\v"
"Hallo Welt!\v"
"Ciao mondo!\v"
,
"+Ok\v"
"+Ok\v"
"+Approvazione\v"
,
"-Cancel\v"
"-Abbrechen\v"
"-Annullamento\v"
};
int Language = strstr(I18N[0], language()) / 3;
string tr(string s)
{
string t = lookup(I18N, s, Language, '\v');
return t ? t : s;
}
dlgDialog(tr("I18N Demo")) {
dlgHBoxLayout dlgSpacing(350);
dlgLabel(tr("Hello world!"));
dlgHBoxLayout {
dlgPushButton(tr("+Ok")) dlgAccept();
dlgPushButton(tr("-Cancel")) dlgReject();
}
};
</pre>
<a name=262>
<h1>lookup()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Looks up data in a string array.
<dt>
<b>Syntax</b>
<dd>
<tt>string lookup(string array[], string key, int field_index[, char separator]);</tt><br>
<tt>string lookup(string array[], string key, string field_name[, char separator]);</tt>
<dt>
<b>Returns</b>
<dd>
<tt>lookup</tt> returns the value of the field identified by <tt>field_index</tt>
or <tt>field_name</tt>.<br>
If the field doesn't exist, or no string matching <tt>key</tt> is found,
an empty string is returned.
</dl>
<b>See also</b> <a href=#253>fileread</a>,
<a href=#278>strsplit</a>
<p>
An <tt>array</tt> that can be used with <tt>lookup()</tt> consists of strings of text,
each string representing one data record.
<p>
Each data record contains an arbitrary number of fields, which are separated by
the character <tt>separator</tt> (default is <tt>'\t'</tt>, the tabulator).
The first field in a record is used as the <tt>key</tt> and is numbered <tt>0</tt>.
<p>
All records must have unique <tt>key</tt> fields and none of the <tt>key</tt> fields
may be empty - otherwise it is undefined which record will be found.
<p>
If the first string in the <tt>array</tt> contains a "Header" record (i.e. a record where
each field describes its contents), using <tt>lookup</tt> with a <tt>field_name</tt>
string automatically determines the index of that field. This allows using the
<tt>lookup</tt> function without exactly knowing which field index contains
the desired data.<br>
It is up to the user to make sure that the first record actually
contains header information.
<p>
If the <tt>key</tt> parameter in the call to <tt>lookup()</tt> is an empty
string, the first string of the <tt>array</tt> will be used. This allows a program to
determine whether there is a header record with the required field names.
<p>
If a field contains the <tt>separator</tt> character, that field must be enclosed
in double quotes (as in <tt>"abc;def"</tt>, assuming the semicolon (<tt>';'</tt>)
is used as separator). The same applies if the field contains double quotes
(<tt>"</tt>), in which case the double quotes inside the field have to be doubled
(as in <tt>"abc;""def"";ghi"</tt>, which would be <tt>abc;"def";ghi</tt>).<br>
<b>It is best to use the default "tab" separator, which doesn't have these problems
(no field can contain a tabulator).</b>
<p>
Here's an example data file (<tt>';'</tt> has been used as separator for better readability):
<pre>
Name;Manufacturer;Code;Price
7400;Intel;I-01-234-97;$0.10
68HC12;Motorola;M68HC1201234;$3.50
</pre>
<h2>Example</h2>
<pre>
string OrderCodes[];
if (fileread(OrderCodes, "ordercodes") &gt; 0) {
if (lookup(OrderCodes, "", "Code", ';')) {
schematic(SCH) {
SCH.parts(P) {
string OrderCode;
// both following statements do exactly the same:
OrderCode = lookup(OrderCodes, P.device.name, "Code", ';');
OrderCode = lookup(OrderCodes, P.device.name, 2, ';');
}
}
}
else
dlgMessageBox("Missing 'Code' field in file 'ordercodes');
}
</pre>
<a name=263>
<h1>palette()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Returns color palette information.
<dt>
<b>Syntax</b>
<dd>
<tt>int palette(int index[, int type]);</tt>
<dt>
<b>Returns</b>
<dd>
The <tt>palette</tt> function returns an integer ARGB value in the form 0xaarrggbb,
or the type of the currently used palette (depending on the value of <tt>index</tt>).
</dl>
The <tt>palette</tt> function returns the ARGB value of the color with the given
<tt>index</tt> (which may be in the range 0..PALETTE_ENTRIES-1). If <tt>type</tt> is not
given (or is <tt>-1</tt>) the palette assigned to the current editor window will
be used. Otherwise <tt>type</tt> specifies which color palette to use (PALETTE_BLACK,
PALETTE_WHITE or PALETTE_COLORED).
<p>
The special value <tt>-1</tt> for <tt>index</tt> makes the function return the type
of the palette that is currently in use by the editor window.
<p>
If either <tt>index</tt> or <tt>type</tt> is out of range, an error message will be
given and the ULP will be terminated.
<h2>Constants</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>PALETTE_TYPES</tt> </td><td width=20><td>the number of palette types (3)</td></tr>
<tr><td><tt>PALETTE_BLACK</tt> </td><td width=20><td>the black background palette (0)</td></tr>
<tr><td><tt>PALETTE_WHITE</tt> </td><td width=20><td>the white background palette (1)</td></tr>
<tr><td><tt>PALETTE_COLORED</tt> </td><td width=20><td>the colored background palette (2)</td></tr>
<tr><td><tt>PALETTE_ENTRIES</tt> </td><td width=20><td>the number of colors per palette (64)</td></tr>
</table>
<a name=264>
<h1>sort()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Sorts an array or a set of arrays.
<dt>
<b>Syntax</b>
<dd>
<tt>void sort(int number, array1[, array2,...]);</tt>
</dl>
The <tt>sort</tt> function either directly sorts a given <tt>array1</tt>,
or it sorts a set of arrays (starting with <tt>array2</tt>), in which case
<tt>array1</tt> is supposed to be an array of <b>int</b>, which will
be used as a pointer array.
<p>
In any case, the <tt>number</tt> argument defines the number of items in the
array(s).
<h2>Sorting a single array</h2>
If the <tt>sort</tt> function is called with one single array, that array
will be sorted directly, as in the following example:
<pre>
string A[];
int n = 0;
A[n++] = "World";
A[n++] = "Hello";
A[n++] = "The truth is out there...";
sort(n, A);
for (int i = 0; i &lt; n; ++i)
printf(A[i]);
</pre>
<h2>Sorting a set of arrays</h2>
If the <tt>sort</tt> function is called with more than one array, the first
array must be an array of <b>int</b>, while all of the other arrays may be
of any array type and hold the data to be sorted. The following example
illustrates how the first array will be used as a pointer:
<pre>
numeric string Nets[], Parts[], Instances[], Pins[];
int n = 0;
int index[];
schematic(S) {
S.nets(N) N.pinrefs(P) {
Nets[n] = N.name;
Parts[n] = P.part.name;
Instances[n] = P.instance.name;
Pins[n] = P.pin.name;
++n;
}
sort(n, index, Nets, Parts, Instances, Pins);
for (int i = 0; i &lt; n; ++i)
printf("%-8s %-8s %-8s %-8s\n",
Nets[index[i]], Parts[index[i]],
Instances[index[i]], Pins[index[i]]);
}
</pre>
The idea behind this is that one net can have several pins connected to it,
and in a netlist you might want to have the net names sorted, and within
one net you also want the part names sorted and so on.
<p>
Note the use of the keyword <tt>numeric</tt> in the string arrays. This causes
the strings to be sorted in a way that takes into account a numeric part
at the end of the strings, which leads to IC1, IC2,... IC9, IC10 instead of
the alphabetical order IC1, IC10, IC2,...IC9.
<p>
When sorting a set of arrays, the first (index) array must be of type
<tt><a href=#166>int</a></tt> and need not be initialized. Any
contents the index array might have before calling the <tt>sort</tt>
function will be overwritten by the resulting index values.
<a name=265>
<h1>status()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Displays a status message in the status bar.
<dt>
<b>Syntax</b>
<dd>
<tt>void status(string message);</tt><br>
</dl>
<b>See also</b> <a href=#306>dlgMessageBox()</a>
<p>
The <tt>status</tt> function displays the given <tt>message</tt> in the status bar of the
editor window in which the ULP is running.
</dl>
<a name=266>
<h1>system()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Executes an external program.
<dt>
<b>Syntax</b>
<dd>
<tt>int system(string command);</tt>
<dt>
<b>Returns</b>
<dd>
The <tt>system</tt> function returns the exit status of the command. This is
typically <tt>0</tt> if everything was ok, and non-zero in case of an error.
</dl>
The <tt>system</tt> function executes the external program given by the <tt>command</tt>
string, and waits until the program ends.
<p>
As a security precaution, you will be prompted with the <tt>command</tt>
string before the command is executed, in order to make sure there is no "evil"
ULP that executes unwanted external commands.
If this dialog is canceled, the <tt>system()</tt> call will return <tt>-1</tt>.
If the dialog is confirmed, any future <tt>system()</tt> calls in the current
EAGLE session with exactly the same command string will be executed without
any further confirmation dialog.
<h2>Input/Output redirection</h2>
If the external program shall read its standard input from (or write its standard
output to) a particular file, input/output needs to be redirected.
<p>
<table><tr><td valign="top"><img src="platforms-lin.png"><br><img src="platforms-mac.png"></td><td valign="middle">
On <b>Linux</b> and <b>Mac OS X</b> this is done by simply adding a <tt>'&lt;'</tt> or
<tt>'&gt;'</tt> to the command line, followed by the desired file name, as in
<pre>
system("program &lt; infile &gt; outfile");
</pre>
which runs <tt>program</tt> and makes it read from <tt>infile</tt> and write
to <tt>outfile</tt>.
</td></tr></table>
<p>
<table><tr><td valign="top"><img src="platforms-win.png"></td><td valign="middle">
On <b>Windows</b> you have to explicitly run a command processor to do this, as in
<pre>
system("cmd.exe /c program &lt; infile &gt; outfile");
</pre>
(on DOS based Windows systems use <tt>command.com</tt> instead of <tt>cmd.exe</tt>).
</td></tr></table>
<h2>Background execution</h2>
The <tt>system</tt> function waits until the given program has ended.
This is useful for programs that only run for a few seconds, or completely
take over the user's attention.
<p>
<table><tr><td valign="top"><img src="platforms-lin.png"><br><img src="platforms-mac.png"></td><td valign="middle">
If an external program runs for a longer time, and you want the system
call to return immediately, without waiting for the program to end, you
can simply add an <tt>'&amp;'</tt> to the command string under <b>Linux</b> and
<b>Mac OS X</b>, as in
<pre>
system("program &amp;");
</pre>
</td></tr></table>
<p>
<table><tr><td valign="top"><img src="platforms-win.png"></td><td valign="middle">
Under Windows you need to explicitly run a command processor to do this, as in
<pre>
system("cmd.exe /c start program");
</pre>
(on DOS based Windows systems use <tt>command.com</tt> instead of <tt>cmd.exe</tt>).
</td></tr></table>
<h2>Example</h2>
<pre>
int result = system("simulate -f filename");
</pre>
This would call a simulation program, giving it a file which the ULP has
just created.
Note that <tt>simulate</tt> here is just an example, it is not part of the EAGLE package!
<a name=267>
<h1>Unit Conversions</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Converts internal units.
<dt>
<b>Syntax</b>
<dd>
<tt>real u2inch(int n);</tt><br>
<tt>real u2mic(int n);</tt><br>
<tt>real u2mil(int n);</tt><br>
<tt>real u2mm(int n);</tt>
<dt>
<b>Returns</b>
<dd>
<tt>u2inch</tt> returns the value of <tt>n</tt> in <i>inch</i>.<br>
<tt>u2mic </tt> returns the value of <tt>n</tt> in <i>microns</i> (1/1000mm).<br>
<tt>u2mil </tt> returns the value of <tt>n</tt> in <i>mil</i> (1/1000inch).<br>
<tt>u2mm </tt> returns the value of <tt>n</tt> in <i>millimeters</i>.
</dl>
<b>See also</b> <a href=#186>UL_GRID</a>
<p>
EAGLE stores all coordinate and size values as <tt><a href=#166>int</a></tt>
values with a resolution of 1/10000mm (0.1&micro;). The above unit conversion
functions can be used to convert these internal units to the desired
measurement units.
<h2>Example</h2>
<pre>
board(B) {
B.elements(E) {
printf("%s at (%f, %f)\n", E.name,
u2mm(E.x), u2mm(E.y));
}
}
</pre>
<a name=268>
<h1>Printing Functions</h1>
<i>Printing functions</i> are used to print formatted strings.
<p>
The following printing functions are available:
<ul>
<li><a href=#269>printf()</a>
<li><a href=#270>sprintf()</a>
</ul>
<a name=269>
<h1>printf()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Writes formatted output to a file.
<dt>
<b>Syntax</b>
<dd>
<tt>int printf(string format[, argument, ...]);</tt>
<dt>
<b>Returns</b>
<dd>
The <tt>printf</tt> function returns the number of characters written
to the file that has been opened by the most recent <a href=#297>output</a>
statement.
<p>
In case of an error, <tt>printf</tt> returns <tt>-1</tt>.
</dl>
<b>See also</b> <a href=#270>sprintf</a>,
<a href=#297>output</a>,
<a href=#248>fileerror</a>
<h2>Format string</h2>
The format string controls how the arguments will be converted,
formatted and printed. There must be exactly as many arguments
as necessary for the format. The number and type of arguments
will be checked against the format, and any mismatch will lead
to an error message.
<p>
The format string contains two types of objects - <i>plain characters</i>
and <i>format specifiers</i>:
<ul>
<li>Plain characters are simply copied verbatim to the output
<li>Format specifiers fetch arguments from the argument list
and apply formatting to them
</ul>
<h2>Format specifiers</h2>
A format specifier has the following form:
<p>
<tt>% [flags] [width] [.prec] type</tt>
<p>
Each format specification begins with the percent character (<tt>%</tt>).
After the <tt>%</tt> comes the following, in this order:
<ul>
<li>an optional sequence of flag characters, <tt>[flags]</tt>
<li>an optional width specifier, <tt>[width]</tt>
<li>an optional precision specifier, <tt>[.prec]</tt>
<li>the conversion type character, <tt>type</tt>
</ul>
<h2>Conversion type characters</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>d</tt> </td><td width=20><td><b>signed</b> decimal <b>int</b></td></tr>
<tr><td><tt>o</tt> </td><td width=20><td><b>unsigned</b> octal <b>int</b></td></tr>
<tr><td><tt>u</tt> </td><td width=20><td><b>unsigned</b> decimal <b>int</b></td></tr>
<tr><td><tt>x</tt> </td><td width=20><td><b>unsigned</b> hexadecimal <b>int</b> (with <b>a</b>, <b>b</b>,...)</td></tr>
<tr><td><tt>X</tt> </td><td width=20><td><b>unsigned</b> hexadecimal <b>int</b> (with <b>A</b>, <b>B</b>,...)</td></tr>
<tr><td><tt>f</tt> </td><td width=20><td><b>signed real</b> value of the form <tt>[-]dddd.dddd</tt></td></tr>
<tr><td><tt>e</tt> </td><td width=20><td><b>signed real</b> value of the form <tt>[-]d.dddd</tt>e<tt>[&plusmn;]ddd</tt></td></tr>
<tr><td><tt>E</tt> </td><td width=20><td>same as <tt>e</tt>, but with <b>E</b> for exponent</td></tr>
<tr><td><tt>g</tt> </td><td width=20><td><b>signed real</b> value in either <tt>e</tt> or <tt>f</tt> form, based on given value and precision</td></tr>
<tr><td><tt>G</tt> </td><td width=20><td>same as <tt>g</tt>, but with <b>E</b> for exponent if <tt>e</tt> format used</td></tr>
<tr><td><tt>c</tt> </td><td width=20><td>single character</td></tr>
<tr><td><tt>s</tt> </td><td width=20><td>character string</td></tr>
<tr><td><tt>%</tt> </td><td width=20><td>the <tt>%</tt> character is printed</td></tr>
</table>
<h2>Flag characters</h2>
The following flag characters can appear in any order and combination.
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>"-"</tt> </td><td width=20><td>the formatted item is left-justified within the field; normally, items are right-justified</td></tr>
<tr><td><tt>"+"</tt> </td><td width=20><td>a signed, positive item will always start with a plus character (<tt>+</tt>); normally, only negative items begin with a sign</td></tr>
<tr><td><tt>" "</tt> </td><td width=20><td>a signed, positive item will always start with a space character; if both <tt>"+"</tt> and <tt>" "</tt> are specified, <tt>"+"</tt> overrides <tt>" "</tt></td></tr>
</table>
<h2>Width specifiers</h2>
The width specifier sets the minimum field width for an output value.
<p>
Width is specified either directly, through a decimal digit string, or
indirectly, through an asterisk (<tt>*</tt>). If you use an asterisk for the
width specifier, the next argument in the call (which must be an <tt>int</tt>)
specifies the minimum output field width.
<p>
In no case does a nonexistent or small field width cause truncation of
a field. If the result of a conversion is wider than the field width,
the field is simply expanded to contain the conversion result.
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt><i>n</i></tt> </td><td width=20><td>At least <i>n</i> characters are printed. If the output value has less than <i>n</i> characters, the output is padded with blanks (right-padded if <tt>"-"</tt> flag given, left-padded otherwise).</td></tr>
<tr><td><tt>0<i>n</i></tt> </td><td width=20><td>At least <i>n</i> characters are printed. If the output value has less than <i>n</i> characters, it is filled on the left with zeroes.</td></tr>
<tr><td><tt>*</tt> </td><td width=20><td>The argument list supplies the width specifier, which must precede the actual argument being formatted.</td></tr>
</table>
<h2>Precision specifiers</h2>
A precision specifier always begins with a period (<tt>.</tt>) to
separate it from any preceding width specifier. Then, like width,
precision is specified either directly through a decimal digit string, or
indirectly, through an asterisk (<tt>*</tt>). If you use an asterisk for the
precision specifier, the next argument in the call (which must be an <tt>int</tt>)
specifies the precision.
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>none </td><td width=20><td>Precision set to default.</td></tr>
<tr><td><tt>.0</tt> </td><td width=20><td>For <tt>int</tt> types, precision is set to default; for <tt>real</tt> types, no decimal point is printed.</td></tr>
<tr><td><tt>.<i>n</i></tt> </td><td width=20><td><i>n</i> characters or <i>n</i> decimal places are printed. If the output value has more than <i>n</i> characters the output might be truncated or rounded (depending on the type character).</td></tr>
<tr><td><tt>*</tt> </td><td width=20><td>The argument list supplies the precision specifier, which must precede the actual argument being formatted.</td></tr>
</table>
<h2>Default precision values</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>douxX</tt> </td><td width=20><td>1</td></tr>
<tr><td><tt>eEf</tt> </td><td width=20><td>6</td></tr>
<tr><td><tt>gG</tt> </td><td width=20><td>all significant digits</td></tr>
<tr><td><tt>c</tt> </td><td width=20><td>no effect</td></tr>
<tr><td><tt>s</tt> </td><td width=20><td>print entire string</td></tr>
</table>
<h2>How precision specification (<tt>.n</tt>) affects conversion</h2>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>douxX</tt> </td><td width=20><td><i>.n</i> specifies that at least <i>n</i> characters are printed. If the input argument has less than <i>n</i> digits, the output value is left-padded with zeros. If the input argument has more than <i>n</i> digits, the output value is <b>not</b> truncated.</td></tr>
<tr><td><tt>eEf</tt> </td><td width=20><td><i>.n</i> specifies that <i>n</i> characters are printed after the decimal point, and the last digit printed is rounded.</td></tr>
<tr><td><tt>gG</tt> </td><td width=20><td><i>.n</i> specifies that at most <i>n</i> significant digits are printed.</td></tr>
<tr><td><tt>c</tt> </td><td width=20><td><i>.n</i> has no effect on the output.</td></tr>
<tr><td><tt>s</tt> </td><td width=20><td><i>.n</i> specifies that no more than <i>n</i> characters are printed.</td></tr>
</table>
<h2>Binary zero characters</h2>
Unlike <a href=#270>sprintf</a>, the <tt>printf</tt> function can print binary zero characters (0x00).
<pre>
char c = 0x00;
printf("%c", c);
</pre>
<h2>Example</h2>
<pre>
int i = 42;
real r = 3.14;
char c = 'A';
string s = "Hello";
printf("Integer: %8d\n", i);
printf("Hex: %8X\n", i);
printf("Real: %8f\n", r);
printf("Char: %-8c\n", c);
printf("String: %-8s\n", s);
</pre>
<a name=270>
<h1>sprintf()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Writes formatted output into a string.
<dt>
<b>Syntax</b>
<dd>
<tt>int sprintf(string result, string format[, argument, ...]);</tt>
<dt>
<b>Returns</b>
<dd>
The <tt>sprintf</tt> function returns the number of characters written
into the <tt>result</tt> string.
<p>
In case of an error, <tt>sprintf</tt> returns <tt>-1</tt>.
</dl>
<b>See also</b> <a href=#269>printf</a>
<h2>Format string</h2>
See <a href=#269>printf</a>.
<h2>Binary zero characters</h2>
Note that <tt>sprintf</tt> can not return strings with embedded binary zero
characters (0x00). If the resulting string contains a binary zero character,
any characters following that zero character will be dropped.
Use <a href=#269>printf</a> if you need to output binary data.
<h2>Example</h2>
<pre>
string result;
int number = 42;
sprintf(result, "The number is %d", number);
</pre>
<a name=271>
<h1>String Functions</h1>
<i>String functions</i> are used to manipulate character strings.
<p>
The following string functions are available:
<ul>
<li><a href=#272>strchr()</a>
<li><a href=#273>strjoin()</a>
<li><a href=#274>strlen()</a>
<li><a href=#275>strlwr()</a>
<li><a href=#276>strrchr()</a>
<li><a href=#277>strrstr()</a>
<li><a href=#278>strsplit()</a>
<li><a href=#279>strstr()</a>
<li><a href=#280>strsub()</a>
<li><a href=#281>strtod()</a>
<li><a href=#282>strtol()</a>
<li><a href=#283>strupr()</a>
<li><a href=#284>strxstr()</a>
</ul>
<a name=272>
<h1>strchr()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Scans a string for the first occurrence of a given character.
<dt>
<b>Syntax</b>
<dd>
<tt>int strchr(string s, char c[, int index]);</tt>
<dt>
<b>Returns</b>
<dd>
The <tt>strchr</tt> function returns the integer offset of the
character in the string, or <tt>-1</tt> if the character does not
occur in the string.
</dl>
<b>See also</b> <a href=#276>strrchr</a>,
<a href=#279>strstr</a>
<p>
If <tt>index</tt> is given, the search starts at that position.
Negative values are counted from the end of the string.
<h2>Example</h2>
<pre>
string s = "This is a string";
char c = 'a';
int pos = strchr(s, c);
if (pos &gt;= 0)
printf("The character %c is at position %d\n", c, pos);
else
printf("The character was not found\n");
</pre>
<a name=273>
<h1>strjoin()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Joins a string array to form a single string.
<dt>
<b>Syntax</b>
<dd>
<tt>string strjoin(string array[], char separator);</tt>
<dt>
<b>Returns</b>
<dd>
The <tt>strjoin</tt> function returns the combined entries of <tt>array</tt>.
</dl>
<b>See also</b> <a href=#278>strsplit</a>,
<a href=#262>lookup</a>,
<a href=#253>fileread</a>
<p>
<tt>strjoin</tt> joins all entries in <tt>array</tt>, delimited by the given
<tt>separator</tt> and returns the resulting string.
<p>
If <tt>separator</tt> is the newline character (<tt>"\n"</tt>) the resulting
string will be terminated with a newline character.
This is done to have a text file that
consists of N lines (each of which is terminated with a newline) and is read
in with the <a href=#253>fileread()</a> function and
<a href=#278>split</a> into
an array of N strings to be joined to the original string as read from the file.
<h2>Example</h2>
<pre>
string a[] = { "Field 1", "Field 2", "Field 3" };
string s = strjoin(a, ':');
</pre>
<a name=274>
<h1>strlen()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Calculates the length of a string.
<dt>
<b>Syntax</b>
<dd>
<tt>int strlen(string s);</tt>
<dt>
<b>Returns</b>
<dd>
The <tt>strlen</tt> function returns the number of characters in
the string.
</dl>
<h2>Example</h2>
<pre>
string s = "This is a string";
int l = strlen(s);
printf("The string is %d characters long\n", l);
</pre>
<a name=275>
<h1>strlwr()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Converts uppercase letters in a string to lowercase.
<dt>
<b>Syntax</b>
<dd>
<tt>string strlwr(string s);</tt>
<dt>
<b>Returns</b>
<dd>
The <tt>strlwr</tt> function returns the modified string.
The original string (given as parameter) is not changed.
</dl>
<b>See also</b> <a href=#283>strupr</a>,
<a href=#246>tolower</a>
<h2>Example</h2>
<pre>
string s = "This Is A String";
string r = strlwr(s);
printf("Prior to strlwr: %s - after strlwr: %s\n", s, r);
</pre>
<a name=276>
<h1>strrchr()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Scans a string for the last occurrence of a given character.
<dt>
<b>Syntax</b>
<dd>
<tt>int strrchr(string s, char c[, int index]);</tt>
<dt>
<b>Returns</b>
<dd>
The <tt>strrchr</tt> function returns the integer offset of the
character in the string, or <tt>-1</tt> if the character does not
occur in the string.
</dl>
<b>See also</b> <a href=#272>strchr</a>,
<a href=#277>strrstr</a>
<p>
If <tt>index</tt> is given, the search starts at that position.
Negative values are counted from the end of the string.
<h2>Example</h2>
<pre>
string s = "This is a string";
char c = 'a';
int pos = strrchr(s, c);
if (pos &gt;= 0)
printf("The character %c is at position %d\n", c, pos);
else
printf("The character was not found\n");
</pre>
<a name=277>
<h1>strrstr()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Scans a string for the last occurrence of a given substring.
<dt>
<b>Syntax</b>
<dd>
<tt>int strrstr(string s1, string s2[, int index]);</tt>
<dt>
<b>Returns</b>
<dd>
The <tt>strrstr</tt> function returns the integer offset of the
first character of s2 in s1, or <tt>-1</tt> if the substring does not
occur in the string.
</dl>
<b>See also</b> <a href=#279>strstr</a>,
<a href=#276>strrchr</a>
<p>
If <tt>index</tt> is given, the search starts at that position.
Negative values are counted from the end of the string.
<h2>Example</h2>
<pre>
string s1 = "This is a string", s2 = "is a";
int pos = strrstr(s1, s2);
if (pos &gt;= 0)
printf("The substring starts at %d\n", pos);
else
printf("The substring was not found\n");
</pre>
<a name=278>
<h1>strsplit()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Splits a string into separate fields.
<dt>
<b>Syntax</b>
<dd>
<tt>int strsplit(string &amp;array[], string s, char separator);</tt>
<dt>
<b>Returns</b>
<dd>
The <tt>strsplit</tt> function returns the number of entries copied into <tt>array</tt>.
</dl>
<b>See also</b> <a href=#273>strjoin</a>,
<a href=#262>lookup</a>,
<a href=#253>fileread</a>
<p>
<tt>strsplit</tt> splits the string <tt>s</tt> at the given <tt>separator</tt>
and stores the resulting fields in the <tt>array</tt>.
<p>
If <tt>separator</tt> is the newline character (<tt>"\n"</tt>) the last field
will be silently dropped if it is empty. This is done to have a text file that
consists of N lines (each of which is terminated with a newline) and is read
in with the <a href=#253>fileread()</a> function to be split into
an array of N strings. With any other <tt>separator</tt> an empty field at the
end of the string will count, so <tt>"a:b:c:"</tt> will result in 4 fields,
the last of which is empty.
<h2>Example</h2>
<pre>
string a[];
int n = strsplit(a, "Field 1:Field 2:Field 3", ':');
</pre>
<a name=279>
<h1>strstr()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Scans a string for the first occurrence of a given substring.
<dt>
<b>Syntax</b>
<dd>
<tt>int strstr(string s1, string s2[, int index]);</tt>
<dt>
<b>Returns</b>
<dd>
The <tt>strstr</tt> function returns the integer offset of the
first character of s2 in s1, or <tt>-1</tt> if the substring does not
occur in the string.
</dl>
<b>See also</b> <a href=#277>strrstr</a>,
<a href=#272>strchr</a>,
<a href=#284>strxstr</a>
<p>
If <tt>index</tt> is given, the search starts at that position.
Negative values are counted from the end of the string.
<h2>Example</h2>
<pre>
string s1 = "This is a string", s2 = "is a";
int pos = strstr(s1, s2);
if (pos &gt;= 0)
printf("The substring starts at %d\n", pos);
else
printf("The substring was not found\n");
</pre>
<a name=280>
<h1>strsub()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Extracts a substring from a string.
<dt>
<b>Syntax</b>
<dd>
<tt>string strsub(string s, int start[, int length]);</tt>
<dt>
<b>Returns</b>
<dd>
The <tt>strsub</tt> function returns the substring indicated by
the <tt>start</tt> and <tt>length</tt> value.
<p>
The value for <tt>length</tt> must be positive, otherwise an empty string
will be returned. If <tt>length</tt> is ommitted, the rest of the string
(beginning at <tt>start</tt>) is returned.
<p>
If <tt>start</tt> points to a position outside the string, an empty string
is returned.
</dl>
<h2>Example</h2>
<pre>
string s = "This is a string";
string t = strsub(s, 4, 7);
printf("The extracted substring is: %s\n", t);
</pre>
<a name=281>
<h1>strtod()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Converts a string to a real value.
<dt>
<b>Syntax</b>
<dd>
<tt>real strtod(string s);</tt>
<dt>
<b>Returns</b>
<dd>
The <tt>strtod</tt> function returns the numerical representation
of the given string as a <tt>real</tt> value. Conversion ends at the
first character that does not fit into the format of a
<a href=#153>real constant</a>.
If an error occurs during conversion of the string <tt>0.0</tt>
will be returned.
</dl>
<b>See also</b> <a href=#282>strtol</a>
<h2>Example</h2>
<pre>
string s = "3.1415";
real r = strtod(s);
printf("The value is %f\n", r);
</pre>
<a name=282>
<h1>strtol()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Converts a string to an integer value.
<dt>
<b>Syntax</b>
<dd>
<tt>int strtol(string s);</tt>
<dt>
<b>Returns</b>
<dd>
The <tt>strtol</tt> function returns the numerical representation
of the given string as an <tt>int</tt> value. Conversion ends at the
first character that does not fit into the format of an
<a href=#152>integer constant</a>.
If an error occurs during conversion of the string <tt>0</tt>
will be returned.
</dl>
<b>See also</b> <a href=#281>strtod</a>
<h2>Example</h2>
<pre>
string s = "1234";
int i = strtol(s);
printf("The value is %d\n", i);
</pre>
<a name=283>
<h1>strupr()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Converts lowercase letters in a string to uppercase.
<dt>
<b>Syntax</b>
<dd>
<tt>string strupr(string s);</tt>
<dt>
<b>Returns</b>
<dd>
The <tt>strupr</tt> function returns the modified string.
The original string (given as parameter) is not changed.
</dl>
<b>See also</b> <a href=#275>strlwr</a>,
<a href=#246>toupper</a>
<h2>Example</h2>
<pre>
string s = "This Is A String";
string r = strupr(s);
printf("Prior to strupr: %s - after strupr: %s\n", s, r);
</pre>
<a name=284>
<h1>strxstr()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Scans a string for the first occurrence of a given regular expression.
<dt>
<b>Syntax</b>
<dd>
<tt>int strxstr(string s1, string s2[, int index[, int &amp;length]]);</tt>
<dt>
<b>Returns</b>
<dd>
The <tt>strxstr</tt> function returns the integer offset of the substring
in s1 that matches the regular expression in s2, or <tt>-1</tt> if
the regular expression does not match in the string.
</dl>
<b>See also</b> <a href=#279>strstr</a>,
<a href=#272>strchr</a>,
<a href=#277>strrstr</a>
<p>
If <tt>index</tt> is given, the search starts at that position.
Negative values are counted from the end of the string.
<p>
If <tt>length</tt> is given, the actual length of the matching substring
is returned in that variable.
<p>
<i>Regular expressions</i> allow you to find a pattern within a text string.
For instance, the regular expression "i.*a" would find a sequence of characters
that starts with an 'i', followed by any character ('.') any number of times ('*'),
and ends with an 'a'. It would match on "is a" as well as "is this a" or "ia".<br>
Details on regular expressions can be found, for instance, in the book
<i>Mastering Regular Expressions</i> by Jeffrey E. F. Friedl.
<h2>Example</h2>
<pre>
string s1 = "This is a string", s2 = "i.*a";
int len = 0;
int pos = strxstr(s1, s2, 0, len);
if (pos &gt;= 0)
printf("The substring starts at %d and is %d charcaters long\n", pos, len);
else
printf("The substring was not found\n");
</pre>
<a name=285>
<h1>Time Functions</h1>
<i>Time functions</i> are used to get and process time and date
information.
<p>
The following time functions are available:
<ul>
<li><a href=#288>t2day()</a>
<li><a href=#288>t2dayofweek()</a>
<li><a href=#288>t2hour()</a>
<li><a href=#288>t2minute()</a>
<li><a href=#288>t2month()</a>
<li><a href=#288>t2second()</a>
<li><a href=#288>t2string()</a>
<li><a href=#288>t2year()</a>
<li><a href=#286>time()</a>
<li><a href=#287>timems()</a>
</ul>
<a name=286>
<h1>time()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Gets the current system time.
<dt>
<b>Syntax</b>
<dd>
<tt>int time(void);</tt>
<dt>
<b>Returns</b>
<dd>
The <tt>time</tt> function returns the current system time as the number
of seconds elapsed since a system dependent reference date.
</dl>
<b>See also</b> <a href=#288>Time Conversions</a>,
<a href=#251>filetime</a>,
<a href=#287>timems()</a>
<h2>Example</h2>
<pre>
int CurrentTime = time();
</pre>
<a name=287>
<h1>timems()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Gets the number of milliseconds since the start of the ULP.
<dt>
<b>Syntax</b>
<dd>
<tt>int timems(void);</tt>
<dt>
<b>Returns</b>
<dd>
The <tt>timems</tt> function returns the number of milliseconds since the
start of the ULP.
<p>
After 86400000 milliseconds (i.e. every 24 hours), the value starts at 0 again.
</dl>
<b>See also</b> <a href=#286>time</a>
<h2>Example</h2>
<pre>
int elapsed = timems();
</pre>
<a name=288>
<h1>Time Conversions</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Convert a time value to day, month, year etc.
<dt>
<b>Syntax</b>
<dd>
<tt>int t2day(int t);</tt><br>
<tt>int t2dayofweek(int t);</tt><br>
<tt>int t2hour(int t);</tt><br>
<tt>int t2minute(int t);</tt><br>
<tt>int t2month(int t);</tt><br>
<tt>int t2second(int t);</tt><br>
<tt>int t2year(int t);</tt><br>
<br>
<tt>string t2string(int t);</tt>
<dt>
<b>Returns</b>
<dd>
<tt>t2day </tt> returns the day of the month (<tt>1</tt>..<tt>31</tt>)<br>
<tt>t2dayofweek</tt> returns the day of the week (<tt>0</tt>=sunday..<tt>6</tt>)<br>
<tt>t2hour </tt> returns the hour (<tt>0</tt>..<tt>23</tt>)<br>
<tt>t2minute </tt> returns the minute (<tt>0</tt>..<tt>59</tt>)<br>
<tt>t2month </tt> returns the month (<tt>0</tt>..<tt>11</tt>)<br>
<tt>t2second </tt> returns the second (<tt>0</tt>..<tt>59</tt>)<br>
<tt>t2year </tt> returns the year (including century!)<br>
<tt>t2string </tt> returns a formatted string containing date and time
</dl>
<b>See also</b> <a href=#286>time</a>
<h2>Example</h2>
<pre>
int t = time();
printf("It is now %02d:%02d:%02d\n",
t2hour(t), t2minute(t), t2second(t));
</pre>
<a name=289>
<h1>Object Functions</h1>
<i>Object functions</i> are used to access common information about objects.
<p>
The following object functions are available:
<ul>
<li><a href=#290>clrgroup()</a>
<li><a href=#291>ingroup()</a>
<li><a href=#292>setgroup()</a>
</ul>
<a name=290>
<h1>clrgroup()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Clears the group flags of an object.
<dt>
<b>Syntax</b>
<dd>
<tt>void clrgroup(object);</tt>
<dt>
</dl>
<b>See also</b> <a href=#291>ingroup()</a>,
<a href=#292>setgroup()</a>,
<a href=#54>GROUP command</a>
<p>
The <tt>clrgroup()</tt> function clears the group flags of the given object,
so that it is no longer part of the previously defined group.
<p>
When applied to an object that contains other objects (like a UL_BOARD or
UL_NET) the group flags of all contained objects are cleared recursively.
<h2>Example</h2>
<pre>
board(B) {
B.elements(E)
clrgroup(E);
}
</pre>
<a name=291>
<h1>ingroup()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Checks whether an object is in the group.
<dt>
<b>Syntax</b>
<dd>
<tt>int ingroup(object);</tt>
<dt>
<b>Returns</b>
<dd>
The <tt>ingroup</tt> function returns a non-zero value if the given object is
in the group.
</dl>
<b>See also</b> <a href=#290>clrgroup()</a>,
<a href=#292>setgroup()</a>,
<a href=#54>GROUP command</a>
<p>
If a group has been defined in the editor, the <tt>ingroup()</tt> function can
be used to check whether a particular object is part of the group.
<p>
Objects with a single coordinate that are individually selectable in the current
drawing (like UL_TEXT, UL_VIA, UL_CIRCLE etc.) return a non-zero value
in a call to <tt>ingroup()</tt> if that coordinate is within the defined group.
<p>
A UL_WIRE returns 0, 1, 2 or 3, depending on whether none, the first, the second
or both of its end points are in the group.
<p>
A UL_RECTANGLE and UL_FRAME returns a non-zero value if one or more of its corners are in the group.
The value has bit 0 set for the upper right corner, bit 1 for the upper left, bit 2
for the bottom left, and bit 3 for the bottom right corner.
<p>
Objects that have no coordinates (like UL_NET, UL_SEGMENT, UL_SIGNAL etc.) return
a non-zero value if one or more of the objects within them are in the group.
<p>
UL_CONTACTREF and UL_PINREF, though not having coordinates of their own, return
a non-zero value if the referenced UL_CONTACT or UL_PIN, respectively, is within
the group.
<h2>Example</h2>
<pre>
output("group.txt") {
board(B) {
B.elements(E) {
if (ingroup(E))
printf("Element %s is in the group\n", E.name);
}
}
}
</pre>
<a name=292>
<h1>setgroup()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Sets the group flags of an object.
<dt>
<b>Syntax</b>
<dd>
<tt>void setgroup(object[, int flags]);</tt>
</dl>
<b>See also</b> <a href=#290>clrgroup()</a>,
<a href=#291>ingroup()</a>,
<a href=#54>GROUP command</a>
<p>
The <tt>setgroup()</tt> function sets the group flags of the given object,
so that it becomes part of the group.
<p>
If no <tt>flags</tt> are given, the object is added to the group as a whole
(i.e. all of its selection points, in case it has more than one).
<p>
If <tt>flags</tt> has a non-zero value, only the group flags of the given
points of the object are set. For a UL_WIRE this means that <tt>'1'</tt>
sets the group flag of the first point, <tt>'2'</tt> that of the second point,
and <tt>'3'</tt> sets both. Any previously set group flags remain unchanged
by a call to <tt>setgroup()</tt>.
<p>
When applied to an object that contains other objects (like a UL_BOARD or
UL_NET) the group flags of all contained objects are set recursively.
<h2>Example</h2>
<pre>
board(B) {
B.elements(E)
setgroup(E);
}
</pre>
<a name=293>
<h1>Builtin Statements</h1>
<i>Builtin statements</i> are generally used to open a certain context in which
data structures of files can be accessed.
<p>
The general syntax of a builtin statement is
<pre>
name(parameters) statement
</pre>
where <tt>name</tt> is the name of the builtin statement, <tt>parameters</tt>
stands for one or more parameters, and <tt>statement</tt> is the code that
will be executed inside the context opened by the builtin statement.
<p>
Note that <tt>statement</tt> can be a compound statement, as in
<pre>
board(B) {
B.elements(E) printf("Element: %s\n", E.name);
B.Signals(S) printf("Signal: %s\n", S.name);
}
</pre>
The following builtin statements are available:
<ul>
<li><a href=#294>board()</a>
<li><a href=#295>deviceset()</a>
<li><a href=#296>library()</a>
<li><a href=#297>output()</a>
<li><a href=#298>package()</a>
<li><a href=#299>schematic()</a>
<li><a href=#300>sheet()</a>
<li><a href=#301>symbol()</a>
</ul>
<a name=294>
<h1>board()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Opens a board context.
<dt>
<b>Syntax</b>
<dd>
<tt>board(identifier) statement</tt>
</dl>
<b>See also</b> <a href=#299>schematic</a>,
<a href=#296>library</a>
<p>
The <tt>board</tt> statement opens a board context if the current editor
window contains a board drawing. A variable of type
<a href=#175>UL_BOARD</a> is created and is given
the name indicated by <tt>identifier</tt>.
<p>
Once the board context is successfully opened and a board variable has been
created, the <tt>statement</tt> is executed. Within the scope of the
<tt>statement</tt> the board variable can be accessed to retrieve further
data from the board.
<p>
If the current editor window does not contain a board drawing, an error
message is given and the ULP is terminated.
<h2>Check if there is a board</h2>
By using the <tt>board</tt> statement without an argument you can check
if the current editor window contains a board drawing. In that case,
<tt>board</tt> behaves like an integer constant, returning <tt>1</tt> if
there is a board drawing in the current editor window, and <tt>0</tt>
otherwise.
<h2>Accessing board from a schematic</h2>
If the current editor window contains a schematic drawing, you can still
access that schematic's board by preceding the <tt>board</tt> statement
with the prefix <tt>project</tt>, as in
<pre>
project.board(B) { ... }
</pre>
This will open a board context regardless whether the current editor window
contains a board or a schematic drawing. However, there must be an editor
window containing that board somewhere on the desktop!
<h2>Example</h2>
<pre>
if (board)
board(B) {
B.elements(E)
printf("Element: %s\n", E.name);
}
</pre>
<a name=295>
<h1>deviceset()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Opens a device set context.
<dt>
<b>Syntax</b>
<dd>
<tt>deviceset(identifier) statement</tt>
</dl>
<b>See also</b> <a href=#298>package</a>,
<a href=#301>symbol</a>,
<a href=#296>library</a>
<p>
The <tt>deviceset</tt> statement opens a device set context if the current editor
window contains a device drawing. A variable of type
<a href=#182>UL_DEVICESET</a> is created and is given
the name indicated by <tt>identifier</tt>.
<p>
Once the device set context is successfully opened and a device set variable has been
created, the <tt>statement</tt> is executed. Within the scope of the
<tt>statement</tt> the device set variable can be accessed to retrieve further
data from the device set.
<p>
If the current editor window does not contain a device drawing, an error
message is given and the ULP is terminated.
<h2>Check if there is a device set</h2>
By using the <tt>deviceset</tt> statement without an argument you can check
if the current editor window contains a device drawing. In that case,
<tt>deviceset</tt> behaves like an integer constant, returning <tt>1</tt> if
there is a device drawing in the current editor window, and <tt>0</tt>
otherwise.
<h2>Example</h2>
<pre>
if (deviceset)
deviceset(D) {
D.gates(G)
printf("Gate: %s\n", G.name);
}
</pre>
<a name=296>
<h1>library()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Opens a library context.
<dt>
<b>Syntax</b>
<dd>
<tt>library(identifier) statement</tt>
</dl>
<b>See also</b> <a href=#294>board</a>,
<a href=#299>schematic</a>,
<a href=#295>deviceset</a>,
<a href=#298>package</a>,
<a href=#301>symbol</a>
<p>
The <tt>library</tt> statement opens a library context if the current editor
window contains a library drawing. A variable of type
<a href=#192>UL_LIBRARY</a> is created and is given
the name indicated by <tt>identifier</tt>.
<p>
Once the library context is successfully opened and a library variable has been
created, the <tt>statement</tt> is executed. Within the scope of the
<tt>statement</tt> the library variable can be accessed to retrieve further
data from the library.
<p>
If the current editor window does not contain a library drawing, an error
message is given and the ULP is terminated.
<h2>Check if there is a library</h2>
By using the <tt>library</tt> statement without an argument you can check
if the current editor window contains a library drawing. In that case,
<tt>library</tt> behaves like an integer constant, returning <tt>1</tt> if
there is a library drawing in the current editor window, and <tt>0</tt>
otherwise.
<h2>Example</h2>
<pre>
if (library)
library(L) {
L.devices(D)
printf("Device: %s\n", D.name);
}
</pre>
<a name=297>
<h1>output()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Opens an output file for subsequent printf() calls.
<dt>
<b>Syntax</b>
<dd>
<tt>output(string filename[, string mode]) statement</tt>
</dl>
<b>See also</b> <a href=#269>printf</a>,
<a href=#248>fileerror</a>
<p>
The <tt>output</tt> statement opens a file with the given <tt>filename</tt>
and <tt>mode</tt> for output through subsequent printf() calls.
If the file has been successfully opened, the <tt>statement</tt> is
executed, and after that the file is closed.
<p>
If the file cannot be opened, an error message is given and execution
of the ULP is terminated.
<p>
By default the output file is written into the <b>Project</b> directory.
<h2>File Modes</h2>
The <tt>mode</tt> parameter defines how the output file is to be opened.
If no <tt>mode</tt> parameter is given, the default is <tt>"wt"</tt>.
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>a</tt> </td><td width=20><td>append to an existing file, or create a new file if it does not exist</td></tr>
<tr><td><tt>w</tt> </td><td width=20><td>create a new file (overwriting an existing file)</td></tr>
<tr><td><tt>t</tt> </td><td width=20><td>open file in text mode</td></tr>
<tr><td><tt>b</tt> </td><td width=20><td>open file in binary mode</td></tr>
<tr><td><tt>D</tt> </td><td width=20><td>delete this file when ending the EAGLE session (only works together with <tt>w</tt>)</td></tr>
<tr><td><tt>F</tt> </td><td width=20><td>force using this file name (normally *.brd, *.sch and *.lbr are rejected)</td></tr>
</table>
<p>
Mode characters may appear in any order and combination. However, only the
last one of <tt>a</tt> and <tt>w</tt> or <tt>t</tt> and <tt>b</tt>, respectively,
is significant. For example a mode of <tt>"abtw"</tt> would open a file for
textual write, which would be the same as <tt>"wt"</tt>.
<h2>Nested Output statements</h2>
<tt>output</tt> statements can be nested, as long as there are enough file
handles available, and provided that no two active <tt>output</tt> statements
access the <b>same</b> file.
<h2>Example</h2>
<pre>
void PrintText(string s)
{
printf("This also goes into the file: %s\n", s);
}
output("file.txt", "wt") {
printf("Directly printed\n");
PrintText("via function call");
}
</pre>
<a name=298>
<h1>package()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Opens a package context.
<dt>
<b>Syntax</b>
<dd>
<tt>package(identifier) statement</tt>
</dl>
<b>See also</b> <a href=#296>library</a>,
<a href=#295>deviceset</a>,
<a href=#301>symbol</a>
<p>
The <tt>package</tt> statement opens a package context if the current editor
window contains a package drawing. A variable of type
<a href=#194>UL_PACKAGE</a> is created and is given
the name indicated by <tt>identifier</tt>.
<p>
Once the package context is successfully opened and a package variable has been
created, the <tt>statement</tt> is executed. Within the scope of the
<tt>statement</tt> the package variable can be accessed to retrieve further
data from the package.
<p>
If the current editor window does not contain a package drawing, an error
message is given and the ULP is terminated.
<h2>Check if there is a package</h2>
By using the <tt>package</tt> statement without an argument you can check
if the current editor window contains a package drawing. In that case,
<tt>package</tt> behaves like an integer constant, returning <tt>1</tt> if
there is a package drawing in the current editor window, and <tt>0</tt>
otherwise.
<h2>Example</h2>
<pre>
if (package)
package(P) {
P.contacts(C)
printf("Contact: %s\n", C.name);
}
</pre>
<a name=299>
<h1>schematic()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Opens a schematic context.
<dt>
<b>Syntax</b>
<dd>
<tt>schematic(identifier) statement</tt>
</dl>
<b>See also</b> <a href=#294>board</a>,
<a href=#296>library</a>,
<a href=#300>sheet</a>
<p>
The <tt>schematic</tt> statement opens a schematic context if the current editor
window contains a schematic drawing. A variable of type
<a href=#201>UL_SCHEMATIC</a> is created and is given
the name indicated by <tt>identifier</tt>.
<p>
Once the schematic context is successfully opened and a schematic variable has been
created, the <tt>statement</tt> is executed. Within the scope of the
<tt>statement</tt> the schematic variable can be accessed to retrieve further
data from the schematic.
<p>
If the current editor window does not contain a schematic drawing, an error
message is given and the ULP is terminated.
<h2>Check if there is a schematic</h2>
By using the <tt>schematic</tt> statement without an argument you can check
if the current editor window contains a schematic drawing. In that case,
<tt>schematic</tt> behaves like an integer constant, returning <tt>1</tt> if
there is a schematic drawing in the current editor window, and <tt>0</tt>
otherwise.
<h2>Accessing schematic from a board</h2>
If the current editor window contains a board drawing, you can still
access that board's schematic by preceding the <tt>schematic</tt> statement
with the prefix <tt>project</tt>, as in
<pre>
project.schematic(S) { ... }
</pre>
This will open a schematic context regardless whether the current editor window
contains a schematic or a board drawing. However, there must be an editor
window containing that schematic somewhere on the desktop!
<h2>Access the current Sheet</h2>
Use the <tt><a href=#300>sheet</a></tt> statement to
directly access the currently loaded sheet.
<h2>Example</h2>
<pre>
if (schematic)
schematic(S) {
S.parts(P)
printf("Part: %s\n", P.name);
}
</pre>
<a name=300>
<h1>sheet()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Opens a sheet context.
<dt>
<b>Syntax</b>
<dd>
<tt>sheet(identifier) statement</tt>
</dl>
<b>See also</b> <a href=#299>schematic</a>
<p>
The <tt>sheet</tt> statement opens a sheet context if the current editor
window contains a sheet drawing. A variable of type
<a href=#203>UL_SHEET</a> is created and is given
the name indicated by <tt>identifier</tt>.
<p>
Once the sheet context is successfully opened and a sheet variable has been
created, the <tt>statement</tt> is executed. Within the scope of the
<tt>statement</tt> the sheet variable can be accessed to retrieve further
data from the sheet.
<p>
If the current editor window does not contain a sheet drawing, an error
message is given and the ULP is terminated.
<h2>Check if there is a sheet</h2>
By using the <tt>sheet</tt> statement without an argument you can check
if the current editor window contains a sheet drawing. In that case,
<tt>sheet</tt> behaves like an integer constant, returning <tt>1</tt> if
there is a sheet drawing in the current editor window, and <tt>0</tt>
otherwise.
<h2>Example</h2>
<pre>
if (sheet)
sheet(S) {
S.parts(P)
printf("Part: %s\n", P.name);
}
</pre>
<a name=301>
<h1>symbol()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Opens a symbol context.
<dt>
<b>Syntax</b>
<dd>
<tt>symbol(identifier) statement</tt>
</dl>
<b>See also</b> <a href=#296>library</a>,
<a href=#295>deviceset</a>,
<a href=#298>package</a>
<p>
The <tt>symbol</tt> statement opens a symbol context if the current editor
window contains a symbol drawing. A variable of type
<a href=#206>UL_SYMBOL</a> is created and is given
the name indicated by <tt>identifier</tt>.
<p>
Once the symbol context is successfully opened and a symbol variable has been
created, the <tt>statement</tt> is executed. Within the scope of the
<tt>statement</tt> the symbol variable can be accessed to retrieve further
data from the symbol.
<p>
If the current editor window does not contain a symbol drawing, an error
message is given and the ULP is terminated.
<h2>Check if there is a symbol</h2>
By using the <tt>symbol</tt> statement without an argument you can check
if the current editor window contains a symbol drawing. In that case,
<tt>symbol</tt> behaves like an integer constant, returning <tt>1</tt> if
there is a symbol drawing in the current editor window, and <tt>0</tt>
otherwise.
<h2>Example</h2>
<pre>
if (symbol)
symbol(S) {
S.pins(P)
printf("Pin: %s\n", P.name);
}
</pre>
<a name=302>
<h1>Dialogs</h1>
User Language Dialogs allow you to define your own frontend to a User Language Program.
<p>
The following sections describe User Language Dialogs in detail:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><a href=#303>Predefined Dialogs</a> </td><td width=20><td>describes the ready to use standard dialogs</td></tr>
<tr><td><a href=#307>Dialog Objects</a> </td><td width=20><td>defines the objects that can be used in a dialog</td></tr>
<tr><td><a href=#331>Layout Information</a> </td><td width=20><td>explains how to define the location of objects within a dialog</td></tr>
<tr><td><a href=#332>Dialog Functions</a> </td><td width=20><td>describes special functions for use with dialogs</td></tr>
<tr><td><a href=#338>A Complete Example</a> </td><td width=20><td>shows a complete ULP with a data entry dialog</td></tr>
</table>
<a name=303>
<h1>Predefined Dialogs</h1>
<i>Predefined Dialogs</i> implement the typical standard dialogs that are frequently used
for selecting file names or issuing error messages.
<p>
The following predefined dialogs are available:
<ul>
<li><a href=#304>dlgDirectory()</a>
<li><a href=#305>dlgFileOpen()</a>
<li><a href=#305>dlgFileSave()</a>
<li><a href=#306>dlgMessageBox()</a>
</ul>
See <a href=#307>Dialog Objects</a> for information on how to
define your own complex user dialogs.
<a name=304>
<h1>dlgDirectory()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Displays a directory dialog.
<dt>
<b>Syntax</b>
<dd>
<tt>string dlgDirectory(string Title[, string Start])</tt>
<dt>
<b>Returns</b>
<dd>
The <tt>dlgDirectory</tt> function returns the full pathname of the selected directory.<br>
If the user has canceled the dialog, the result will be an empty string.
</dl>
<b>See also</b> <a href=#305>dlgFileOpen</a>
<p>
The <tt>dlgDirectory</tt> function displays a directory dialog from which the user can
select a directory.
<p>
<tt>Title</tt> will be used as the dialog's title.
<p>
If <tt>Start</tt> is not empty, it will be used as the starting point for the <tt>dlgDirectory</tt>.
<h2>Example</h2>
<pre>
string dirName;
dirName = dlgDirectory("Select a directory", "");
</pre>
<a name=305>
<h1>dlgFileOpen(), dlgFileSave()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Displays a file dialog.
<dt>
<b>Syntax</b>
<dd>
<tt>string dlgFileOpen(string Title[, string Start[, string Filter]])</tt><br>
<tt>string dlgFileSave(string Title[, string Start[, string Filter]])</tt>
<dt>
<b>Returns</b>
<dd>
The <tt>dlgFileOpen</tt> and <tt>dlgFileSave</tt> functions return the full pathname of the selected file.<br>
If the user has canceled the dialog, the result will be an empty string.
</dl>
<b>See also</b> <a href=#304>dlgDirectory</a>
<p>
The <tt>dlgFileOpen</tt> and <tt>dlgFileSave</tt> functions display a file dialog from which the user can
select a file.
<p>
<tt>Title</tt> will be used as the dialog's title.
<p>
If <tt>Start</tt> is not empty, it will be used as the starting point for the file dialog.
Otherwise the current directory will be used.
<p>
Only files matching <tt>Filter</tt> will be displayed. If <tt>Filter</tt> is empty, all files will
be displayed.
<p>
<tt>Filter</tt> can be either a simple wildcard (as in <tt>"*.brd"</tt>), a list of
wildcards (as in <tt>"*.bmp&nbsp;*.jpg"</tt>) or may even contain descriptive text, as in
<tt>"Bitmap&nbsp;files&nbsp;(*.bmp)"</tt>. If the "File type" combo box of the file dialog shall
contain several entries, they have to be separated by double semicolons, as in
<tt>"Bitmap&nbsp;files&nbsp;(*.bmp);;Other&nbsp;images&nbsp;(*.jpg&nbsp;*.png)"</tt>.
<h2>Example</h2>
<pre>
string fileName;
fileName = dlgFileOpen("Select a file", "", "*.brd");
</pre>
<a name=306>
<h1>dlgMessageBox()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Displays a message box.
<dt>
<b>Syntax</b>
<dd>
<tt>int dlgMessageBox(string Message[, <i>button_list</i>])</tt>
<dt>
<b>Returns</b>
<dd>
The <tt>dlgMessageBox</tt> function returns the index of the button the user has selected.<br>
The first button in <tt>button_list</tt> has index <tt>0</tt>.
</dl>
<b>See also</b> <a href=#265>status()</a>
<p>
The <tt>dlgMessageBox</tt> function displays the given <tt>Message</tt> in a modal dialog and
waits until the user selects one of the buttons defined in <tt>button_list</tt>.
<p>
If <tt>Message</tt> contains any HTML tags, the characters '&lt;', '&gt;' and '&amp;'
must be given as "&amp;lt;", "&amp;gt;" and "&amp;amp;", respectively, if they shall
be displayed as such.
<p>
<tt>button_list</tt> is an optional list of comma separated strings, which defines the
set of buttons that will be displayed at the bottom of the message box.<br>
A maximum of three buttons can be defined.
If no <tt>button_list</tt> is given, it defaults to <tt>"OK"</tt>.
<p>
The first button in <tt>button_list</tt> will become the default button (which will be selected
if the user hits ENTER), and the last button in the list will become the "cancel button", which
is selected if the user hits ESCape or closes the message box. You can make a different
button the default button by starting its name with a <tt>'+'</tt>, and you can make
a different button the cancel button by starting its name with a <tt>'-'</tt>.
To start a button text with an actual <tt>'+'</tt> or <tt>'-'</tt> it has to be <a href=#337>escaped</a>.
<p>
If a button text contains an <tt>'&amp;'</tt>, the character following the ampersand
will become a hotkey, and when the user hits the corresponding key, that button will be selected.
To have an actual <tt>'&amp;'</tt> character in the text it has to be <a href=#337>escaped</a>.
<p>
The message box can be given an icon by setting the first character of <tt>Message</tt> to<br>
&nbsp;&nbsp;&nbsp;<tt>'<b>;</b>'</tt> - for an <i>Information</i><br>
&nbsp;&nbsp;&nbsp;<tt>'<b>!</b>'</tt> - for a <i>Warning</i><br>
&nbsp;&nbsp;&nbsp;<tt>'<b>:</b>'</tt> - for an <i>Error</i><br>
If, however, the <tt>Message</tt> shall begin with one of these characters, it has to be <a href=#337>escaped</a>.
<p>
<table><tr><td valign="top"><img src="platforms-mac.png"></td><td valign="middle">
On <b>Mac OS X</b> only the character <tt>'<b>:</b>'</tt> will actually result in
showing an icon. All others are ignored.
</td></tr></table>
<h2>Example</h2>
<pre>
if (dlgMessageBox("!Are you sure?", "&amp;Yes", "&amp;No") == 0) {
// let's do it!
}
</pre>
<a name=307>
<h1>Dialog Objects</h1>
A User Language Dialog is built from the following <i>Dialog Objects</i>:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><a href=#308>dlgCell</a> </td><td width=20><td>a grid cell context</td></tr>
<tr><td><a href=#309>dlgCheckBox</a> </td><td width=20><td>a checkbox</td></tr>
<tr><td><a href=#310>dlgComboBox</a> </td><td width=20><td>a combo box selection field</td></tr>
<tr><td><a href=#311>dlgDialog</a> </td><td width=20><td>the basic container of any dialog</td></tr>
<tr><td><a href=#312>dlgGridLayout</a> </td><td width=20><td>a grid based layout context</td></tr>
<tr><td><a href=#313>dlgGroup</a> </td><td width=20><td>a group field</td></tr>
<tr><td><a href=#314>dlgHBoxLayout</a> </td><td width=20><td>a horizontal box layout context</td></tr>
<tr><td><a href=#315>dlgIntEdit</a> </td><td width=20><td>an integer entry field</td></tr>
<tr><td><a href=#316>dlgLabel</a> </td><td width=20><td>a text label</td></tr>
<tr><td><a href=#317>dlgListBox</a> </td><td width=20><td>a list box</td></tr>
<tr><td><a href=#318>dlgListView</a> </td><td width=20><td>a list view</td></tr>
<tr><td><a href=#319>dlgPushButton</a> </td><td width=20><td>a push button</td></tr>
<tr><td><a href=#320>dlgRadioButton</a></td><td width=20><td>a radio button</td></tr>
<tr><td><a href=#321>dlgRealEdit</a> </td><td width=20><td>a real entry field</td></tr>
<tr><td><a href=#322>dlgSpacing</a> </td><td width=20><td>a layout spacing object</td></tr>
<tr><td><a href=#323>dlgSpinBox</a> </td><td width=20><td>a spin box selection field</td></tr>
<tr><td><a href=#324>dlgStretch</a> </td><td width=20><td>a layout stretch object</td></tr>
<tr><td><a href=#325>dlgStringEdit</a> </td><td width=20><td>a string entry field</td></tr>
<tr><td><a href=#326>dlgTabPage</a> </td><td width=20><td>a tab page</td></tr>
<tr><td><a href=#327>dlgTabWidget</a> </td><td width=20><td>a tab page container</td></tr>
<tr><td><a href=#328>dlgTextEdit</a> </td><td width=20><td>a text entry field</td></tr>
<tr><td><a href=#329>dlgTextView</a> </td><td width=20><td>a text viewer field</td></tr>
<tr><td><a href=#330>dlgVBoxLayout</a> </td><td width=20><td>a vertical box layout context</td></tr>
</table>
<p>
<a name=308>
<h1>dlgCell</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Defines a cell location within a grid layout context.
<dt>
<b>Syntax</b>
<dd>
<tt>dlgCell(int row, int column[, int row2, int column2]) <i>statement</i></tt>
</dl>
<b>See also</b> <a href=#312>dlgGridLayout</a>,
<a href=#314>dlgHBoxLayout</a>,
<a href=#330>dlgVBoxLayout</a>,
<a href=#331>Layout Information</a>,
<a href=#338>A Complete Example</a>
<p>
The <tt>dlgCell</tt> statement defines the location of a cell within a
<a href=#312>grid layout context</a>.
<p>
The row and column indexes start at 0, so the upper left cell has the index&nbsp;(0,&nbsp;0).
<p>
With two parameters the dialog object defined by <tt>statement</tt> will be placed in
the single cell addresses by <tt>row</tt> and <tt>column</tt>.
With four parameters the dialog object will span over all cells from <tt>row</tt>/<tt>column</tt>
to <tt>row2</tt>/<tt>column2</tt>.
<p>
By default a <tt>dlgCell</tt> contains a <a href=#314>dlgHBoxLayout</a>,
so if the cell contains more than one dialog object, they will be placed next to
each other horizontally.
<h2>Example</h2>
<pre>
string Text;
dlgGridLayout {
dlgCell(0, 0) dlgLabel("Cell 0,0");
dlgCell(1, 2, 4, 7) dlgTextEdit(Text);
}
</pre>
<a name=309>
<h1>dlgCheckBox</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Defines a checkbox.
<dt>
<b>Syntax</b>
<dd>
<tt>dlgCheckBox(string Text, int &amp;Checked) [ <i>statement</i> ]</tt>
</dl>
<b>See also</b> <a href=#320>dlgRadioButton</a>,
<a href=#313>dlgGroup</a>,
<a href=#331>Layout Information</a>,
<a href=#338>A Complete Example</a>
<p>
The <tt>dlgCheckBox</tt> statement defines a check box with the given <tt>Text</tt>.
<p>
If <tt>Text</tt> contains an <tt>'&amp;'</tt>, the character following the ampersand
will become a hotkey, and when the user hits <tt>Alt+hotkey</tt>, the checkbox will be toggled.
To have an actual <tt>'&amp;'</tt> character in the text it has to be <a href=#337>escaped</a>.
<p>
<tt>dlgCheckBox</tt> is mainly used within a <a href=#313>dlgGroup</a>,
but can also be used otherwise.<br>
All check boxes within the same dialog must have <b>different</b> <tt>Checked</tt> variables!
<p>
If the user checks a <tt>dlgCheckBox</tt>, the associated <tt>Checked</tt> variable is set
to <tt>1</tt>, otherwise it is set to <tt>0</tt>.
The initial value of <tt>Checked</tt> defines whether a checkbox is initially checked.
If <tt>Checked</tt> is not equal to <tt>0</tt>, the checkbox is initially checked.
<p>
The optional <tt>statement</tt> is executed every time the <tt>dlgCheckBox</tt> is toggled.
<h2>Example</h2>
<pre>
int mirror = 0;
int rotate = 1;
int flip = 0;
dlgGroup("Orientation") {
dlgCheckBox("&amp;Mirror", mirror);
dlgCheckBox("&amp;Rotate", rotate);
dlgCheckBox("&amp;Flip", flip);
}
</pre>
<a name=310>
<h1>dlgComboBox</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Defines a combo box selection field.
<dt>
<b>Syntax</b>
<dd>
<tt>dlgComboBox(string array[], int &amp;Selected) [ <i>statement</i> ]</tt>
</dl>
<b>See also</b> <a href=#317>dlgListBox</a>,
<a href=#316>dlgLabel</a>,
<a href=#331>Layout Information</a>,
<a href=#338>A Complete Example</a>
<p>
The <tt>dlgComboBox</tt> statement defines a combo box selection field with the contents
of the given <tt>array</tt>.
<p>
<tt>Selected</tt> reflects the index of the selected combo box entry. The first entry has index <tt>0</tt>.
<p>
Each element of <tt>array</tt> defines the contents of one entry in the combo box.
None of the strings in <tt>array</tt> may be empty (if there is an empty string,
all strings after and including that one will be dropped).
<p>
The optional <tt>statement</tt> is executed whenever the selection in the <tt>dlgComboBox</tt> changes.<br>
Before the <tt>statement</tt> is executed, all variables that have been used with dialog objects
are updated to their current values, and any changes made to these variables inside the
<tt>statement</tt> will be reflected in the dialog when the statement returns.
<p>
If the initial value of <tt>Selected</tt> is outside the range of the <tt>array</tt>
indexes, it is set to <tt>0</tt>.
<h2>Example</h2>
<pre>
string Colors[] = { "red", "green", "blue", "yellow" };
int Selected = 2; // initially selects "blue"
dlgComboBox(Colors, Selected) dlgMessageBox("You have selected " + Colors[Selected]);
</pre>
<a name=311>
<h1>dlgDialog</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Executes a User Language Dialog.
<dt>
<b>Syntax</b>
<dd>
<tt>int dlgDialog(string Title) <i>block</i> ;</tt>
<dt>
<b>Returns</b>
<dd>
The <tt>dlgDialog</tt> function returns an integer value that can be given a user defined meaning
through a call to the <tt><a href=#333>dlgAccept()</a></tt> function.<br>
If the dialog is simply closed, the return value will be <tt>0</tt>.
</dl>
<b>See also</b> <a href=#312>dlgGridLayout</a>,
<a href=#314>dlgHBoxLayout</a>,
<a href=#330>dlgVBoxLayout</a>,
<a href=#333>dlgAccept</a>,
<a href=#335>dlgReset</a>,
<a href=#336>dlgReject</a>,
<a href=#338>A Complete Example</a>
<p>
The <tt>dlgDialog</tt> function executes the dialog defined by
<tt><a href=#229>block</a></tt>.
This is the only dialog object that actually is a User Language builtin
function. Therefore it can be used anywhere where a function call is allowed.
<p>
The <tt>block</tt> normally contains only other <a href=#307>dialog objects</a>,
but it is also possible to use other User Language statements, for example to conditionally add
objects to the dialog (see the second example below).
<p>
By default a <tt>dlgDialog</tt> contains a <a href=#330>dlgVBoxLayout</a>,
so a simple dialog doesn't have to worry about the layout.
<p>
A <tt>dlgDialog</tt> should at some point contain a call to the <tt><a href=#333>dlgAccept()</a></tt>
function in order to allow the user to close the dialog and accept its contents.
<p>
If all you need is a simple message box or file dialog you might want to use one of the
<a href=#303>Predefined Dialogs</a> instead.
<h2>Examples</h2>
<pre>
int Result = dlgDialog("Hello") {
dlgLabel("Hello world");
dlgPushButton("+OK") dlgAccept();
};
int haveButton = 1;
dlgDialog("Test") {
dlgLabel("Start");
if (haveButton)
dlgPushButton("Here") dlgAccept();
};
</pre>
<a name=312>
<h1>dlgGridLayout</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Opens a grid layout context.
<dt>
<b>Syntax</b>
<dd>
<tt>dlgGridLayout <i>statement</i></tt>
</dl>
<b>See also</b> <a href=#308>dlgCell</a>,
<a href=#314>dlgHBoxLayout</a>,
<a href=#330>dlgVBoxLayout</a>,
<a href=#331>Layout Information</a>,
<a href=#338>A Complete Example</a>
<p>
The <tt>dlgGridLayout</tt> statement opens a grid layout context.
<p>
The only dialog object that can be used directly in <tt>statement</tt> is
<a href=#308>dlgCell</a>, which defines the location of a particular
dialog object within the grid layout.
<p>
The row and column indexes start at 0, so the upper left cell has the index&nbsp;(0,&nbsp;0).<br>
The number of rows and columns is automatically extended according to the location of
dialog objects that are defined within the grid layout context, so you don't have
to explicitly define the number of rows and columns.
<h2>Example</h2>
<pre>
dlgGridLayout {
dlgCell(0, 0) dlgLabel("Row 0/Col 0");
dlgCell(1, 0) dlgLabel("Row 1/Col 0");
dlgCell(0, 1) dlgLabel("Row 0/Col 1");
dlgCell(1, 1) dlgLabel("Row 1/Col 1");
}
</pre>
<a name=313>
<h1>dlgGroup</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Defines a group field.
<dt>
<b>Syntax</b>
<dd>
<tt>dlgGroup(string Title) <i>statement</i></tt>
</dl>
<b>See also</b> <a href=#309>dlgCheckBox</a>,
<a href=#320>dlgRadioButton</a>,
<a href=#331>Layout Information</a>,
<a href=#338>A Complete Example</a>
<p>
The <tt>dlgGroup</tt> statement defines a group with the given <tt>Title</tt>.
<p>
By default a <tt>dlgGroup</tt> contains a <a href=#330>dlgVBoxLayout</a>,
so a simple group doesn't have to worry about the layout.
<p>
<tt>dlgGroup</tt> is mainly used to contain a set of <a href=#320>radio buttons</a>
or <a href=#309>check boxes</a>, but may as well contain any other objects in its
<tt>statement</tt>.<br>
Radio buttons within a <tt>dlgGroup</tt> are numbered starting with <tt>0</tt>.
<h2>Example</h2>
<pre>
int align = 1;
dlgGroup("Alignment") {
dlgRadioButton("&amp;Top", align);
dlgRadioButton("&amp;Center", align);
dlgRadioButton("&amp;Bottom", align);
}
</pre>
<a name=314>
<h1>dlgHBoxLayout</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Opens a horizontal box layout context.
<dt>
<b>Syntax</b>
<dd>
<tt>dlgHBoxLayout <i>statement</i></tt>
</dl>
<b>See also</b> <a href=#312>dlgGridLayout</a>,
<a href=#330>dlgVBoxLayout</a>,
<a href=#331>Layout Information</a>,
<a href=#338>A Complete Example</a>
<p>
The <tt>dlgHBoxLayout</tt> statement opens a horizontal box layout context for the given
<tt>statement</tt>.
<h2>Example</h2>
<pre>
dlgHBoxLayout {
dlgLabel("Box 1");
dlgLabel("Box 2");
dlgLabel("Box 3");
}
</pre>
<a name=315>
<h1>dlgIntEdit</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Defines an integer entry field.
<dt>
<b>Syntax</b>
<dd>
<tt>dlgIntEdit(int &amp;Value, int Min, int Max)</tt>
</dl>
<b>See also</b> <a href=#321>dlgRealEdit</a>,
<a href=#325>dlgStringEdit</a>,
<a href=#316>dlgLabel</a>,
<a href=#331>Layout Information</a>,
<a href=#338>A Complete Example</a>
<p>
The <tt>dlgIntEdit</tt> statement defines an integer entry field with the given <tt>Value</tt>.
<p>
If <tt>Value</tt> is initially outside the range defined by <tt>Min</tt> and <tt>Max</tt>
it will be limited to these values.
<h2>Example</h2>
<pre>
int Value = 42;
dlgHBoxLayout {
dlgLabel("Enter a &amp;Number between 0 and 99");
dlgIntEdit(Value, 0, 99);
}
</pre>
<a name=316>
<h1>dlgLabel</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Defines a text label.
<dt>
<b>Syntax</b>
<dd>
<tt>dlgLabel(string Text [, int Update])</tt>
</dl>
<b>See also</b> <a href=#331>Layout Information</a>,
<a href=#338>A Complete Example</a>,
<a href=#334>dlgRedisplay()</a>
<p>
The <tt>dlgLabel</tt> statement defines a label with the given <tt>Text</tt>.
<p>
<tt>Text</tt> can be either a string literal, as in <tt>"Hello"</tt>, or a string variable.
<p>
If <tt>Text</tt> contains any HTML tags, the characters '&lt;', '&gt;' and '&amp;'
must be given as "&amp;lt;", "&amp;gt;" and "&amp;amp;", respectively, if they shall
be displayed as such.
<p>
If the <tt>Update</tt> parameter is not <tt>0</tt> and <tt>Text</tt> is a string variable,
its contents can be modified in the <tt>statement</tt> of, e.g., a <a href=#319>dlgPushButton</a>,
and the label will be automatically updated. This, of course, is only
useful if <tt>Text</tt> is a dedicated string variable (not, e.g., the loop variable of
a <tt>for</tt> statement).
<p>
If <tt>Text</tt> contains an <tt>'&amp;'</tt>, and the object following the label
can have the keyboard focus, the character following the ampersand
will become a hotkey, and when the user hits <tt>Alt+hotkey</tt>, the focus will go to the
object that was defined immediately following the <tt>dlgLabel</tt>.
To have an actual <tt>'&amp;'</tt> character in the text it has to be <a href=#337>escaped</a>.
<h2>Example</h2>
<pre>
string OS = "Windows";
dlgHBoxLayout {
dlgLabel(OS, 1);
dlgPushButton("&amp;Change OS") { OS = "Linux"; }
}
</pre>
<a name=317>
<h1>dlgListBox</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Defines a list box selection field.
<dt>
<b>Syntax</b>
<dd>
<tt>dlgListBox(string array[], int &amp;Selected) [ <i>statement</i> ]</tt>
</dl>
<b>See also</b> <a href=#310>dlgComboBox</a>,
<a href=#318>dlgListView</a>,
<a href=#316>dlgLabel</a>,
<a href=#331>Layout Information</a>,
<a href=#338>A Complete Example</a>
<p>
The <tt>dlgListBox</tt> statement defines a list box selection field with the contents
of the given <tt>array</tt>.
<p>
<tt>Selected</tt> reflects the index of the selected list box entry. The first entry has index <tt>0</tt>.
<p>
Each element of <tt>array</tt> defines the contents of one line in the list box.
None of the strings in <tt>array</tt> may be empty (if there is an empty string,
all strings after and including that one will be dropped).
<p>
The optional <tt>statement</tt> is executed whenever the user double clicks on an entry
of the <tt>dlgListBox</tt>.<br>
Before the <tt>statement</tt> is executed, all variables that have been used with dialog objects
are updated to their current values, and any changes made to these variables inside the
<tt>statement</tt> will be reflected in the dialog when the statement returns.
<p>
If the initial value of <tt>Selected</tt> is outside the range of the <tt>array</tt>
indexes, no entry will be selected.
<h2>Example</h2>
<pre>
string Colors[] = { "red", "green", "blue", "yellow" };
int Selected = 2; // initially selects "blue"
dlgListBox(Colors, Selected) dlgMessageBox("You have selected " + Colors[Selected]);
</pre>
<a name=318>
<h1>dlgListView</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Defines a multi column list view selection field.
<dt>
<b>Syntax</b>
<dd>
<tt>dlgListView(string Headers, string array[], int &amp;Selected[, int &amp;Sort]) [ <i>statement</i> ]</tt>
</dl>
<b>See also</b> <a href=#317>dlgListBox</a>,
<a href=#316>dlgLabel</a>,
<a href=#331>Layout Information</a>,
<a href=#338>A Complete Example</a>
<p>
The <tt>dlgListView</tt> statement defines a multi column list view selection field with the contents
of the given <tt>array</tt>.
<p>
<tt>Headers</tt> is the tab separated list of column headers.
<p>
<tt>Selected</tt> reflects the index of the selected list view entry in the <tt>array</tt>
(the sequence in which the entries are actually displayed may be different, because the contents
of a <tt>dlgListView</tt> can be sorted by the various columns).
The first entry has index <tt>0</tt>.<br>
If no particular entry shall be initially selected, <tt>Selected</tt> should be
initialized to <tt>-1</tt>.
<p>
<tt>Sort</tt> defines which column should be used to sort the list view. The leftmost
column is numbered <tt>1</tt>. The sign of this parameter defines the direction in which
to sort (positive values sort in ascending order). If <tt>Sort</tt> is <tt>0</tt> or
outside the valid number of columns, no sorting will be done. The returned value of
<tt>Sort</tt> reflects the column and sort mode selected by the user by clicking
on the list column headers. By default <tt>dlgListView</tt> sorts by the first
column, in ascending order.
<p>
Each element of <tt>array</tt> defines the contents of one line in the list view,
and must contain tab separated values. If there are fewer values in an element of <tt>array</tt>
than there are entries in the <tt>Headers</tt> string the remaining fields will be empty.
If there are more values in an element of <tt>array</tt> than there are entries in the
<tt>Headers</tt> string the superfluous elements will be silently dropped.
None of the strings in <tt>array</tt> may be empty (if there is an empty string,
all strings after and including that one will be dropped).
<p>
A list entry that contains line feeds (<tt>'\n'</tt>) will be displayed in several
lines accordingly.
<p>
The optional <tt>statement</tt> is executed whenever the user double clicks on an entry
of the <tt>dlgListView</tt>.<br>
Before the <tt>statement</tt> is executed, all variables that have been used with dialog objects
are updated to their current values, and any changes made to these variables inside the
<tt>statement</tt> will be reflected in the dialog when the statement returns.
<p>
If the initial value of <tt>Selected</tt> is outside the range of the <tt>array</tt>
indexes, no entry will be selected.
<p>
If <tt>Headers</tt> is an empty string, the first element of the <tt>array</tt> is used
as the header string. Consequently the index of the first entry is then <tt>1</tt>.
<p>
The contents of a <tt>dlgListView</tt> can be sorted by any column by clicking on
that column's header. Columns can also be swapped by "click&amp;dragging" a column
header. Note that none of these changes will have any effect on the contents of the
<tt>array</tt>.
If the contents shall be sorted alphanumerically a <tt>numeric string[]</tt> array
can be used.
<h2>Example</h2>
<pre>
string Colors[] = { "red\tThe color RED", "green\tThe color GREEN", "blue\tThe color BLUE" };
int Selected = 0; // initially selects "red"
dlgListView("Name\tDescription", Colors, Selected) dlgMessageBox("You have selected " + Colors[Selected]);
</pre>
<a name=319>
<h1>dlgPushButton</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Defines a push button.
<dt>
<b>Syntax</b>
<dd>
<tt>dlgPushButton(string Text) <i>statement</i></tt>
</dl>
<b>See also</b> <a href=#331>Layout Information</a>,
<a href=#332>Dialog Functions</a>,
<a href=#338>A Complete Example</a>
<p>
The <tt>dlgPushButton</tt> statement defines a push button with the given <tt>Text</tt>.
<p>
If <tt>Text</tt> contains an <tt>'&amp;'</tt>, the character following the ampersand
will become a hotkey, and when the user hits <tt>Alt+hotkey</tt>, the button will be selected.
To have an actual <tt>'&amp;'</tt> character in the text it has to be <a href=#337>escaped</a>.
<p>
If <tt>Text</tt> starts with a <tt>'+'</tt> character, this button will become the default
button, which will be selected if the user hits ENTER.<br>
If <tt>Text</tt> starts with a <tt>'-'</tt> character, this button will become the cancel
button, which will be selected if the user closes the dialog.<br>
<b>CAUTION: Make sure that the <tt>statement</tt> of such a marked cancel button contains
a call to <a href=#336>dlgReject()</a>! Otherwise the user may be unable
to close the dialog at all!</b><br>
To have an actual <tt>'+'</tt> or <tt>'-'</tt> character as the first character of the text
it has to be <a href=#337>escaped</a>.
<p>
If the user selects a <tt>dlgPushButton</tt>, the given <tt>statement</tt> is executed.<br>
Before the <tt>statement</tt> is executed, all variables that have been used with dialog objects
are updated to their current values, and any changes made to these variables inside the
<tt>statement</tt> will be reflected in the dialog when the statement returns.
<h2>Example</h2>
<pre>
int defaultWidth = 10;
int defaultHeight = 20;
int width = 5;
int height = 7;
dlgPushButton("&amp;Reset defaults") {
width = defaultWidth;
height = defaultHeight;
}
dlgPushButton("+&amp;Accept") dlgAccept();
dlgPushButton("-Cancel") { if (dlgMessageBox("Are you sure?", "Yes", "No") == 0) dlgReject(); }
</pre>
<a name=320>
<h1>dlgRadioButton</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Defines a radio button.
<dt>
<b>Syntax</b>
<dd>
<tt>dlgRadioButton(string Text, int &amp;Selected) [ <i>statement</i> ]</tt>
</dl>
<b>See also</b> <a href=#309>dlgCheckBox</a>,
<a href=#313>dlgGroup</a>,
<a href=#331>Layout Information</a>,
<a href=#338>A Complete Example</a>
<p>
The <tt>dlgRadioButton</tt> statement defines a radio button with the given <tt>Text</tt>.
<p>
If <tt>Text</tt> contains an <tt>'&amp;'</tt>, the character following the ampersand
will become a hotkey, and when the user hits <tt>Alt+hotkey</tt>, the button will be selected.
To have an actual <tt>'&amp;'</tt> character in the text it has to be <a href=#337>escaped</a>.
<p>
<tt>dlgRadioButton</tt> can only be used within a <a href=#313>dlgGroup</a>.<br>
All radio buttons within the same group must use the <b>same</b> <tt>Selected</tt> variable!
<p>
If the user selects a <tt>dlgRadioButton</tt>, the index of that button within the <tt>dlgGroup</tt>
is stored in the <tt>Selected</tt> variable.<br>
The initial value of <tt>Selected</tt> defines which radio button is initially selected.
If <tt>Selected</tt> is outside the valid range for this group, no radio button will be selected.
In order to get the correct radio button selection, <tt>Selected</tt> must be set <b>before</b>
the first <tt>dlgRadioButton</tt> is defined, and must not be modified between adding subsequent
radio buttons. Otherwise it is undefined which (if any) radio button will be selected.
<p>
The optional <tt>statement</tt> is executed every time the <tt>dlgRadioButton</tt> is selected.
<h2>Example</h2>
<pre>
int align = 1;
dlgGroup("Alignment") {
dlgRadioButton("&amp;Top", align);
dlgRadioButton("&amp;Center", align);
dlgRadioButton("&amp;Bottom", align);
}
</pre>
<a name=321>
<h1>dlgRealEdit</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Defines a real entry field.
<dt>
<b>Syntax</b>
<dd>
<tt>dlgRealEdit(real &amp;Value, real Min, real Max)</tt>
</dl>
<b>See also</b> <a href=#315>dlgIntEdit</a>,
<a href=#325>dlgStringEdit</a>,
<a href=#316>dlgLabel</a>,
<a href=#331>Layout Information</a>,
<a href=#338>A Complete Example</a>
<p>
The <tt>dlgRealEdit</tt> statement defines a real entry field with the given <tt>Value</tt>.
<p>
If <tt>Value</tt> is initially outside the range defined by <tt>Min</tt> and <tt>Max</tt>
it will be limited to these values.
<h2>Example</h2>
<pre>
real Value = 1.4142;
dlgHBoxLayout {
dlgLabel("Enter a &amp;Number between 0 and 99");
dlgRealEdit(Value, 0.0, 99.0);
}
</pre>
<a name=322>
<h1>dlgSpacing</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Defines additional space in a box layout context.
<dt>
<b>Syntax</b>
<dd>
<tt>dlgSpacing(int Size)</tt>
</dl>
<b>See also</b> <a href=#314>dlgHBoxLayout</a>,
<a href=#330>dlgVBoxLayout</a>,
<a href=#324>dlgStretch</a>,
<a href=#331>Layout Information</a>,
<a href=#338>A Complete Example</a>
<p>
The <tt>dlgSpacing</tt> statement defines additional space in a vertical or horizontal box layout context.
<p>
<tt>Size</tt> defines the number of pixels of the additional space.
<h2>Example</h2>
<pre>
dlgVBoxLayout {
dlgLabel("Label 1");
dlgSpacing(40);
dlgLabel("Label 2");
}
</pre>
<a name=323>
<h1>dlgSpinBox</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Defines a spin box selection field.
<dt>
<b>Syntax</b>
<dd>
<tt>dlgSpinBox(int &amp;Value, int Min, int Max)</tt>
</dl>
<b>See also</b> <a href=#315>dlgIntEdit</a>,
<a href=#316>dlgLabel</a>,
<a href=#331>Layout Information</a>,
<a href=#338>A Complete Example</a>
<p>
The <tt>dlgSpinBox</tt> statement defines a spin box entry field with the given <tt>Value</tt>.
<p>
If <tt>Value</tt> is initially outside the range defined by <tt>Min</tt> and <tt>Max</tt>
it will be limited to these values.
<h2>Example</h2>
<pre>
int Value = 42;
dlgHBoxLayout {
dlgLabel("&amp;Select value");
dlgSpinBox(Value, 0, 99);
}
</pre>
<a name=324>
<h1>dlgStretch</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Defines an empty stretchable space in a box layout context.
<dt>
<b>Syntax</b>
<dd>
<tt>dlgStretch(int Factor)</tt>
</dl>
<b>See also</b> <a href=#314>dlgHBoxLayout</a>,
<a href=#330>dlgVBoxLayout</a>,
<a href=#322>dlgSpacing</a>,
<a href=#331>Layout Information</a>,
<a href=#338>A Complete Example</a>
<p>
The <tt>dlgStretch</tt> statement defines an empty stretchable space in a vertical or horizontal box layout context.
<p>
<tt>Factor</tt> defines the stretch factor of the space.
<h2>Example</h2>
<pre>
dlgHBoxLayout {
dlgStretch(1);
dlgPushButton("+OK") { dlgAccept(); };
dlgPushButton("Cancel") { dlgReject(); };
}
</pre>
<a name=325>
<h1>dlgStringEdit</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Defines a string entry field.
<dt>
<b>Syntax</b>
<dd>
<tt>dlgStringEdit(string &amp;Text)</tt>
</dl>
<b>See also</b> <a href=#321>dlgRealEdit</a>,
<a href=#315>dlgIntEdit</a>,
<a href=#328>dlgTextEdit</a>,
<a href=#316>dlgLabel</a>,
<a href=#331>Layout Information</a>,
<a href=#338>A Complete Example</a>
<p>
The <tt>dlgStringEdit</tt> statement defines a text entry field with the given <tt>Text</tt>.
<h2>Example</h2>
<pre>
string Name = "Linus";
dlgHBoxLayout {
dlgLabel("Enter &amp;Name");
dlgStringEdit(Name);
}
</pre>
<a name=326>
<h1>dlgTabPage</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Defines a tab page.
<dt>
<b>Syntax</b>
<dd>
<tt>dlgTabPage(string Title) <i>statement</i></tt>
</dl>
<b>See also</b> <a href=#327>dlgTabWidget</a>,
<a href=#331>Layout Information</a>,
<a href=#338>A Complete Example</a>
<p>
The <tt>dlgTabPage</tt> statement defines a tab page with the given <tt>Title</tt> containing
the given <tt>statement</tt>.
<p>
If <tt>Title</tt> contains an <tt>'&amp;'</tt>, the character following the ampersand
will become a hotkey, and when the user hits <tt>Alt+hotkey</tt>, this tab page will be opened.
To have an actual <tt>'&amp;'</tt> character in the text it has to be <a href=#337>escaped</a>.
<p>
Tab pages can only be used within a <a href=#327>dlgTabWidget</a>.
<p>
By default a <tt>dlgTabPage</tt> contains a <a href=#330>dlgVBoxLayout</a>,
so a simple tab page doesn't have to worry about the layout.
<h2>Example</h2>
<pre>
dlgTabWidget {
dlgTabPage("Tab &amp;1") {
dlgLabel("This is page 1");
}
dlgTabPage("Tab &amp;2") {
dlgLabel("This is page 2");
}
}
</pre>
<a name=327>
<h1>dlgTabWidget</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Defines a container for tab pages.
<dt>
<b>Syntax</b>
<dd>
<tt>dlgTabWidget <i>statement</i></tt>
</dl>
<b>See also</b> <a href=#326>dlgTabPage</a>,
<a href=#331>Layout Information</a>,
<a href=#338>A Complete Example</a>
<p>
The <tt>dlgTabWidget</tt> statement defines a container for a set of tab pages.
<p>
<tt>statement</tt> must be a sequence of one or more <a href=#326>dlgTabPage</a> objects.
There must be no other dialog objects in this sequence.
<h2>Example</h2>
<pre>
dlgTabWidget {
dlgTabPage("Tab &amp;1") {
dlgLabel("This is page 1");
}
dlgTabPage("Tab &amp;2") {
dlgLabel("This is page 2");
}
}
</pre>
<a name=328>
<h1>dlgTextEdit</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Defines a multiline text entry field.
<dt>
<b>Syntax</b>
<dd>
<tt>dlgTextEdit(string &amp;Text)</tt>
</dl>
<b>See also</b> <a href=#325>dlgStringEdit</a>,
<a href=#329>dlgTextView</a>,
<a href=#316>dlgLabel</a>,
<a href=#331>Layout Information</a>,
<a href=#338>A Complete Example</a>
<p>
The <tt>dlgTextEdit</tt> statement defines a multiline text entry field with the given <tt>Text</tt>.
<p>
The lines in the <tt>Text</tt> have to be delimited by a newline character (<tt>'\n'</tt>).
Any whitespace characters at the end of the lines contained in <tt>Text</tt> will be
removed, and upon return there will be no whitespace characters at the end of the lines.
Empty lines at the end of the text will be removed entirely.
<h2>Example</h2>
<pre>
string Text = "This is some text.\nLine 2\nLine 3";
dlgVBoxLayout {
dlgLabel("&amp;Edit the text");
dlgTextEdit(Text);
}
</pre>
<a name=329>
<h1>dlgTextView</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Defines a multiline text viewer field.
<dt>
<b>Syntax</b>
<dd>
<tt>dlgTextView(string Text)</tt><br>
<tt>dlgTextView(string Text, string &amp;Link) <i>statement</i></tt>
</dl>
<b>See also</b> <a href=#328>dlgTextEdit</a>,
<a href=#316>dlgLabel</a>,
<a href=#331>Layout Information</a>,
<a href=#338>A Complete Example</a>
<p>
The <tt>dlgTextView</tt> statement defines a multiline text viewer field with the given <tt>Text</tt>.
<p>
The <tt>Text</tt> may contain <a href=#339>HTML</a> tags.
<p>
If <tt>Link</tt> is given and the <tt>Text</tt> contains hyperlinks, <tt>statement</tt>
will be executed every time the user clicks on a hyperlink, with the value of <tt>Link</tt>
set to whatever the <tt>&lt;a href=...&gt;</tt> tag defines as the value of <i>href</i>.
If, after the execution of <tt>statement</tt>, the <tt>Link</tt> variable is not empty,
the default handling of hyperlinks will take place. This is also the case if <tt>Link</tt>
contains some text before dlgTextView is opened, which allows for an initial
scrolling to a given position.
<h2>Example</h2>
<pre>
string Text = "This is some text.\nLine 2\nLine 3";
dlgVBoxLayout {
dlgLabel("&amp;View the text");
dlgTextView(Text);
}
</pre>
<a name=330>
<h1>dlgVBoxLayout</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Opens a vertical box layout context.
<dt>
<b>Syntax</b>
<dd>
<tt>dlgVBoxLayout <i>statement</i></tt>
</dl>
<b>See also</b> <a href=#312>dlgGridLayout</a>,
<a href=#314>dlgHBoxLayout</a>,
<a href=#331>Layout Information</a>,
<a href=#338>A Complete Example</a>
<p>
The <tt>dlgVBoxLayout</tt> statement opens a vertical box layout context for the given
<tt>statement</tt>.
<p>
By default a <a href=#311>dlgDialog</a> contains a <tt>dlgVBoxLayout</tt>,
so a simple dialog doesn't have to worry about the layout.
<h2>Example</h2>
<pre>
dlgVBoxLayout {
dlgLabel("Box 1");
dlgLabel("Box 2");
dlgLabel("Box 3");
}
</pre>
<a name=331>
<h1>Layout Information</h1>
All objects within a User Language Dialog a placed inside a <i>layout context</i>.
<p>
Layout contexts can be either <a href=#312>grid</a>, <a href=#314>horizontal</a>
or <a href=#330>vertical</a>.
<h2>Grid Layout Context</h2>
Objects in a grid layout context must specify the grid coordinates of the cell or cells into
which they shall be placed. To place a text label at row 5, column 2, you would write
<pre>
dlgGridLayout {
dlgCell(5, 2) dlgLabel("Text");
}
</pre>
If the object shall span over more than one cell you need to specify the coordinates of the
starting cell and the ending cell. To place a group that extends from row 1, column 2 up to row 3,
column 5, you would write
<pre>
dlgGridLayout {
dlgCell(1, 2, 3, 5) dlgGroup("Title") {
//...
}
}
</pre>
<h2>Horizontal Layout Context</h2>
Objects in a horizontal layout context are placed left to right.
<p>
The special objects <a href=#324>dlgStretch</a> and <a href=#322>dlgSpacing</a>
can be used to further refine the distribution of the available space.
<p>
To define two buttons that are pushed all the way to the right edge of the dialog,
you would write
<pre>
dlgHBoxLayout {
dlgStretch(1);
dlgPushButton("+OK") dlgAccept();
dlgPushButton("Cancel") dlgReject();
}
</pre>
<h2>Vertical Layout Context</h2>
Objects in a vertical layout context follow the same rules as those in a horizontal
layout context, except that they are placed top to bottom.
<h2>Mixing Layout Contexts</h2>
Vertical, horizontal and grid layout contexts can be mixed to create the desired layout
structure of a dialog.
See the <a href=#338>Complete Example</a> for a demonstration of this.
<a name=332>
<h1>Dialog Functions</h1>
The following functions can be used with User Language Dialogs:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><a href=#333>dlgAccept()</a> </td><td width=20><td>closes the dialog and accepts its contents</td></tr>
<tr><td><a href=#334>dlgRedisplay()</a> </td><td width=20><td>immediately redisplays the dialog after changes to any values</td></tr>
<tr><td><a href=#335>dlgReset()</a> </td><td width=20><td>resets all dialog objects to their initial values</td></tr>
<tr><td><a href=#336>dlgReject()</a> </td><td width=20><td>closes the dialog and rejects its contents</td></tr>
</table>
<a name=333>
<h1>dlgAccept()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Closes the dialog and accepts its contents.
<dt>
<b>Syntax</b>
<dd>
<tt>void dlgAccept([ <i>int Result</i> ]);</tt>
</dl>
<b>See also</b> <a href=#336>dlgReject</a>,
<a href=#311>dlgDialog</a>,
<a href=#338>A Complete Example</a>
<p>
The <tt>dlgAccept</tt> function causes the <a href=#311>dlgDialog</a> to be closed
and return after the current statement sequence has been completed.
<p>
Any changes the user has made to the dialog values will be accepted and are copied into
the variables that have been given when the <a href=#307>dialog objects</a>
were defined.
<p>
The optional <tt>Result</tt> is the value that will be returned by the dialog.
Typically this should be a positive integer value.
If no value is given, it defaults to <tt>1</tt>.
<p>
Note that <tt>dlgAccept()</tt> does return to the normal program execution,
so in a sequence like
<pre>
dlgPushButton("OK") {
dlgAccept();
dlgMessageBox("Accepting!");
}
</pre>
the statement after <tt>dlgAccept()</tt> will still be executed!
<h2>Example</h2>
<pre>
int Result = dlgDialog("Test") {
dlgPushButton("+OK") dlgAccept(42);
dlgPushButton("Cancel") dlgReject();
};
</pre>
<a name=334>
<h1>dlgRedisplay()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Redisplays the dialog after changing values.
<dt>
<b>Syntax</b>
<dd>
<tt>void dlgRedisplay(void);</tt>
</dl>
<b>See also</b> <a href=#335>dlgReset</a>,
<a href=#311>dlgDialog</a>,
<a href=#338>A Complete Example</a>
<p>
The <tt>dlgRedisplay</tt> function can be called to immediately refresh the
<a href=#311>dlgDialog</a> after changes have been made to the variables
used when defining the <a href=#307>dialog objects</a>.
<p>
You only need to call <tt>dlgRedisplay()</tt> if you want the dialog to be refreshed
while still executing program code. In the example below the status is changed
to "Running..." and <tt>dlgRedisplay()</tt> has to be called to make this change
take effect before the "program action" is performed. After the final status
change to "Finished." there is no need to call <tt>dlgRedisplay()</tt>, since
all dialog objects are automatically updated after leaving the statement.
<h2>Example</h2>
<pre>
string Status = "Idle";
int Result = dlgDialog("Test") {
dlgLabel(Status, 1); // note the '1' to tell the label to be updated!
dlgPushButton("+OK") dlgAccept(42);
dlgPushButton("Cancel") dlgReject();
dlgPushButton("Run") {
Status = "Running...";
dlgRedisplay();
// some program action here...
Status = "Finished.";
}
};
</pre>
<a name=335>
<h1>dlgReset()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Resets all dialog objects to their initial values.
<dt>
<b>Syntax</b>
<dd>
<tt>void dlgReset(void);</tt>
</dl>
<b>See also</b> <a href=#336>dlgReject</a>,
<a href=#311>dlgDialog</a>,
<a href=#338>A Complete Example</a>
<p>
The <tt>dlgReset</tt> function copies the initial values back into all
<a href=#307>dialog objects</a> of the current
<a href=#311>dlgDialog</a>.
<p>
Any changes the user has made to the dialog values will be discarded.
<p>
Calling <a href=#336><tt>dlgReject()</tt></a> implies a call
to <tt>dlgReset()</tt>.
<h2>Example</h2>
<pre>
int Number = 1;
int Result = dlgDialog("Test") {
dlgIntEdit(Number);
dlgPushButton("+OK") dlgAccept(42);
dlgPushButton("Cancel") dlgReject();
dlgPushButton("Reset") dlgReset();
};
</pre>
<a name=336>
<h1>dlgReject()</h1>
<dl>
<dt>
<b>Function</b>
<dd>
Closes the dialog and rejects its contents.
<dt>
<b>Syntax</b>
<dd>
<tt>void dlgReject([ <i>int Result</i> ]);</tt>
</dl>
<b>See also</b> <a href=#333>dlgAccept</a>,
<a href=#335>dlgReset</a>,
<a href=#311>dlgDialog</a>,
<a href=#338>A Complete Example</a>
<p>
The <tt>dlgReject</tt> function causes the <a href=#311>dlgDialog</a> to be closed
and return after the current statement sequence has been completed.
<p>
Any changes the user has made to the dialog values will be discarded.
The variables that have been given when the <a href=#307>dialog objects</a>
were defined will be reset to their original values when the dialog returns.
<p>
The optional <tt>Result</tt> is the value that will be returned by the dialog.
Typically this should be <tt>0</tt> or a negative integer value.
If no value is given, it defaults to <tt>0</tt>.
<p>
Note that <tt>dlgReject()</tt> does return to the normal program execution,
so in a sequence like
<pre>
dlgPushButton("Cancel") {
dlgReject();
dlgMessageBox("Rejecting!");
}
</pre>
the statement after <tt>dlgReject()</tt> will still be executed!
<p>
Calling <tt>dlgReject()</tt> implies a call to <a href=#335><tt>dlgReset()</tt></a>.
<h2>Example</h2>
<pre>
int Result = dlgDialog("Test") {
dlgPushButton("+OK") dlgAccept(42);
dlgPushButton("Cancel") dlgReject();
};
</pre>
<a name=337>
<h1>Escape Character</h1>
Some characters have special meanings in button
or label texts, so they need to be <i>escaped</i> if they shall appear literally.
<p>
To do this you need to prepend the character with a <i>backslash</i>, as in
<pre>
dlgLabel("Miller \\&amp; Co.");
</pre>
This will result in "Miller &amp; Co." displayed in the dialog.
<p>
Note that there are actually <b>two</b> backslash characters here, since this line
will first go through the User Language parser, which will strip the first backslash.
<a name=338>
<h1>A Complete Example</h1>
Here's a complete example of a User Language Dialog.
<pre>
int hor = 1;
int ver = 1;
string fileName;
int Result = dlgDialog("Enter Parameters") {
dlgHBoxLayout {
dlgStretch(1);
dlgLabel("This is a simple dialog");
dlgStretch(1);
}
dlgHBoxLayout {
dlgGroup("Horizontal") {
dlgRadioButton("&amp;Top", hor);
dlgRadioButton("&amp;Center", hor);
dlgRadioButton("&amp;Bottom", hor);
}
dlgGroup("Vertical") {
dlgRadioButton("&amp;Left", ver);
dlgRadioButton("C&amp;enter", ver);
dlgRadioButton("&amp;Right", ver);
}
}
dlgHBoxLayout {
dlgLabel("File &amp;name:");
dlgStringEdit(fileName);
dlgPushButton("Bro&amp;wse") {
fileName = dlgFileOpen("Select a file", fileName);
}
}
dlgGridLayout {
dlgCell(0, 0) dlgLabel("Row 0/Col 0");
dlgCell(1, 0) dlgLabel("Row 1/Col 0");
dlgCell(0, 1) dlgLabel("Row 0/Col 1");
dlgCell(1, 1) dlgLabel("Row 1/Col 1");
}
dlgSpacing(10);
dlgHBoxLayout {
dlgStretch(1);
dlgPushButton("+OK") dlgAccept();
dlgPushButton("Cancel") dlgReject();
}
};
</pre>
<a name=339>
<h1>Supported HTML tags</h1>
EAGLE supports a subset of the tags used to format HTML pages.
This can be used to format the text of several <a href=#302>User Language Dialog</a> objects,
in the <tt><a href=#147>#usage</a></tt> directive or in the <a href=#44>description</a>
of library objects.
<p>
Text is considered to be HTML if the first line contains a tag.
If this is not the case, and you want the text to be formatted, you need to
enclose the entire text in the <tt>&lt;html&gt;...&lt;/html&gt;</tt> tag.
<p>
The following table lists all supported HTML tags and their available attributes:
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><b>Tag</b></td><td width=20><td><b>Description</b></td></tr>
<tr><td>&lt;html&gt;...&lt;/html&gt;</td><td width=20><td>An HTML document. It understands the following attributes
<ul>
<li><tt>bgcolor</tt> - The background color, for example <tt>bgcolor="yellow"</tt> or <tt>bgcolor="#0000FF"</tt>.
<li><tt>background</tt> - The background pixmap, for example <tt>background="granit.xpm"</tt>.
<li><tt>text</tt> - The default text color, for example <tt>text="red"</tt>.
<li><tt>link</tt> - The link color, for example <tt>link="green"</tt>.
</ul>
</td></tr>
<tr><td>&lt;h1&gt;...&lt;/h1&gt;</td><td width=20><td>A top-level heading.</td></tr>
<tr><td>&lt;h2&gt;...&lt;/h2&gt;</td><td width=20><td>A sub-level heading.</td></tr>
<tr><td>&lt;h3&gt;...&lt;/h3&gt;</td><td width=20><td>A sub-sub-level heading.</td></tr>
<tr><td>&lt;p&gt;...&lt;/p&gt;</td><td width=20><td>A left-aligned paragraph. Adjust the alignment with the <tt>align</tt> attribute. Possible values are <tt>left</tt>, <tt>right</tt> and <tt>center</tt>.</td></tr>
<tr><td>&lt;center&gt;...&lt;/center&gt;</td><td width=20><td>A centered paragraph.</td></tr>
<tr><td>&lt;blockquote&gt;...&lt;/blockquote&gt;</td><td width=20><td>An indented paragraph, useful for quotes.</td></tr>
<tr><td>&lt;ul&gt;...&lt;/ul&gt;</td><td width=20><td>An un-ordered list. You can also pass a type argument to define the bullet style. The default is <tt>type=disc</tt>, other types are <tt>circle</tt> and <tt>square</tt>.</td></tr>
<tr><td>&lt;ol&gt;...&lt;/ol&gt;</td><td width=20><td>An ordered list. You can also pass a type argument to define the enumeration label style. The default is <tt>type="1"</tt>, other types are <tt>"a"</tt> and <tt>"A"</tt>.</td></tr>
<tr><td>&lt;li&gt;...&lt;/li&gt;</td><td width=20><td>A list item. This tag can only be used within the context of <tt>ol</tt> or <tt>ul</tt>.</td></tr>
<tr><td>&lt;pre&gt;...&lt;/pre&gt;</td><td width=20><td>For larger chunks of code. Whitespaces in the contents are preserved. For small bits of code, use the inline-style <tt>code</tt>.</td></tr>
<tr><td>&lt;a&gt;...&lt;/a&gt;</td><td width=20><td>An anchor or link. It understands the following attributes:
<ul>
<li><tt>href</tt> - The reference target as in <tt>&lt;a href="#123"&gt;...&lt;/a&gt;</tt>.
<li><tt>name</tt> - The anchor name, as in <tt>&lt;a name="123"&gt;...&lt;/a&gt;</tt>.
</ul>
</td></tr>
<tr><td>&lt;em&gt;...&lt;/em&gt;</td><td width=20><td>Emphasized (same as <tt>&lt;i&gt;...&lt;/i&gt;</tt>).</td></tr>
<tr><td>&lt;strong&gt;...&lt;/strong&gt;</td><td width=20><td>Strong (same as <tt>&lt;b&gt;...&lt;/b&gt;</tt>).</td></tr>
<tr><td>&lt;i&gt;...&lt;/i&gt;</td><td width=20><td>Italic font style.</td></tr>
<tr><td>&lt;b&gt;...&lt;/b&gt;</td><td width=20><td>Bold font style.</td></tr>
<tr><td>&lt;u&gt;...&lt;/u&gt;</td><td width=20><td>Underlined font style.</td></tr>
<tr><td>&lt;big&gt;...&lt;/big&gt;</td><td width=20><td>A larger font size.</td></tr>
<tr><td>&lt;small&gt;...&lt;/small&gt;</td><td width=20><td>A smaller font size.</td></tr>
<tr><td>&lt;code&gt;...&lt;/code&gt;</td><td width=20><td>Indicates Code. (same as <tt>&lt;tt&gt;...&lt;/tt&gt;</tt>. For larger chunks of code, use the block-tag <tt>pre</tt>.</td></tr>
<tr><td>&lt;tt&gt;...&lt;/tt&gt;</td><td width=20><td>Typewriter font style.</td></tr>
<tr><td>&lt;font&gt;...&lt;/font&gt;</td><td width=20><td>Customizes the font size, family and text color. The tag understands the following attributes:
<ul>
<li><tt>color</tt> - The text color, for example <tt>color="red"</tt> or <tt>color="#FF0000"</tt>.
<li><tt>size</tt> - The logical size of the font. Logical sizes 1 to 7 are supported. The value may either be absolute, for example <tt>size=3,</tt> or relative like <tt>size=-2</tt>. In the latter case, the sizes are simply added.
<li><tt>face</tt> - The family of the font, for example <tt>face=times</tt>.
</ul>
</td></tr>
<tr><td>&lt;img...&gt;</td><td width=20><td>An image. This tag understands the following attributes:
<ul>
<li><tt>src</tt> - The image name, for example <tt>&lt;img src="image.xpm"&gt;</tt>.<br>
Supported image formats are:<br>
".bmp" (Windows Bitmap Files)<br>
".pbm" (Portable Bitmap Files)<br>
".pgm" (Portable Grayscale Bitmap Files)<br>
".png" (Portable Network Graphics Files)<br>
".ppm" (Portable Pixelmap Files)<br>
".xbm" (X Bitmap Files)<br>
".xpm" (X Pixmap Files)
<li><tt>width</tt> - The width of the image. If the image does not fit to the specified size, it will be scaled automatically.
<li><tt>height</tt> - The height of the image.
<li><tt>align</tt> - Determines where the image is placed. Per default, an image is placed inline, just like a normal character. Specify <tt>left</tt> or <tt>right</tt> to place the image at the respective side.
</ul>
</td></tr>
<tr><td>&lt;hr&gt;</td><td width=20><td>A horizonal line.</td></tr>
<tr><td>&lt;br&gt;</td><td width=20><td>A line break.</td></tr>
<tr><td>&lt;nobr&gt;...&lt;/nobr&gt;</td><td width=20><td>No break. Prevents word wrap.</td></tr>
<tr><td>&lt;table&gt;...&lt;/table&gt;</td><td width=20><td>A table definition.
The default table is frameless. Specify the boolean attribute
<tt>border</tt> in order to get a frame. Other attributes are:
<ul>
<li><tt>bgcolor</tt> - The background color.
<li> <tt>width</tt> - The table width. This is either absolute in pixels or relative in percent of the column width, for example <tt>width=80%</tt>.
<li> <tt>border</tt> - The width of the table border. The default is 0 (= no border).
<li> <tt>cellspacing</tt> - Additional space around the table cells. The default is 2.
<li> <tt>cellpadding</tt> - Additional space around the contents of table cells. Default is 1.
</ul>
</td></tr>
<tr><td>&lt;tr&gt;...&lt;/tr&gt;</td><td width=20><td>A table row. Can only be used within <tt>table</tt>. Understands the attribute
<ul>
<li><tt>bgcolor</tt> - The background color.
</ul>
</td></tr>
<tr><td>&lt;td&gt;...&lt;/td&gt;</td><td width=20><td>A table data cell. Can only be used within <tt>tr.</tt> Understands the attributes
<ul>
<li><tt>bgcolor</tt> - The background color.
<li> <tt>width</tt> - The cell width. This is either absolute in pixels or relative in percent of the entire table width, for example <tt>width=50%</tt>.
<li> <tt>colspan</tt> - Defines how many columns this cell spans. The default is 1.
<li> <tt>rowspan</tt> - Defines how many rows this cell spans. The default is 1.
<li> <tt>align</tt> - Alignment, possible values are <tt>left</tt>, <tt>right</tt> and <tt>center</tt>. The default is left-aligned.
</ul>
</td></tr>
<tr><td>&lt;th&gt;...&lt;/th&gt;</td><td width=20><td>A table header cell. Like <tt>td</tt> but defaults to center-alignment and a bold font.</td></tr>
<tr><td>&lt;author&gt;...&lt;/author&gt;</td><td width=20><td>Marks the author of this text.</td></tr>
<tr><td>&lt;dl&gt;...&lt;/dl&gt;</td><td width=20><td>A definition list.</td></tr>
<tr><td>&lt;dt&gt;...&lt;/dt&gt;</td><td width=20><td>A definition tag. Can only be used within <tt>dl</tt>.</td></tr>
<tr><td>&lt;dd&gt;...&lt;/dd&gt;</td><td width=20><td>Definition data. Can only be used within <tt>dl</tt>.</td></tr>
</table>
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><b>Tag</b></td><td width=20><td><b>Meaning</b></td></tr>
<tr><td>&amp;lt;</td><td width=20><td>&lt;</td></tr>
<tr><td>&amp;gt;</td><td width=20><td>&gt;</td></tr>
<tr><td>&amp;amp;</td><td width=20><td>&amp;</td></tr>
<tr><td>&amp;nbsp;</td><td width=20><td>non-breaking space</td></tr>
<tr><td>&amp;auml;</td><td width=20><td>&auml;</td></tr>
<tr><td>&amp;ouml;</td><td width=20><td>&ouml;</td></tr>
<tr><td>&amp;uuml;</td><td width=20><td>&uuml;</td></tr>
<tr><td>&amp;Auml;</td><td width=20><td>&Auml;</td></tr>
<tr><td>&amp;Ouml;</td><td width=20><td>&Ouml;</td></tr>
<tr><td>&amp;Uuml;</td><td width=20><td>&Uuml;</td></tr>
<tr><td>&amp;szlig;</td><td width=20><td>&szlig;</td></tr>
<tr><td>&amp;copy;</td><td width=20><td>&copy;</td></tr>
<tr><td>&amp;deg;</td><td width=20><td>&deg;</td></tr>
<tr><td>&amp;micro;</td><td width=20><td>&micro;</td></tr>
<tr><td>&amp;plusmn;</td><td width=20><td>&plusmn;</td></tr>
</table>
<a name=340>
<h1>Automatic Backup</h1>
<h2>Maximum backup level</h2>
The WRITE command creates backup copies of the saved files.
These backups have the same name as the original file, with a
modified extension that follows the pattern
<pre>
.x#n
</pre>
In this pattern <tt>'x'</tt> is replaced by the character
<p>
<tt>'b'</tt> for board files<br>
<tt>'s'</tt> for schematic files<br>
<tt>'l'</tt> for library files
<p>
<tt>'n'</tt> stands for a single digit number in
the range 1..9. Higher numbers indicate older files.
<p>
The fixed '#' character makes it easy to delete all backup files
from the operating system, using <b><tt>*.?#?</tt></b> as a wildcard.
<p>
Note that backup files with the same number 'n' do not necessarily
represent consistent combinations of board and schematic files!
<p>
The maximum number of backup copies can be set in the
<a href=#15>backup dialog</a>.
<h2>Auto backup interval</h2>
If a drawing has been modified a safety backup copy will be automatically
created after at most the given <i>Auto backup interval</i>.
<p>
This safety backup file will have a name that follows the pattern
<pre>
.x##
</pre>
In this pattern <tt>'x'</tt> is replaced by the character
<p>
<tt>'b'</tt> for board files<br>
<tt>'s'</tt> for schematic files<br>
<tt>'l'</tt> for library files
<p>
The safety backup file will be deleted after a successful regular save
operation. If the drawing has not been saved with the WRITE command
(e.g. due to a power failure) this file can be renamed and loaded as a
normal board, schematic or library file, repectively.
<p>
The auto backup interval can be set in the <a href=#15>backup dialog</a>.
<a name=341>
<h1>Forward&amp;Back Annotation</h1>
A schematic and board file are logically interconnected through automatic
Forward&amp;Back Annotation. Normally there are no special things to be
considered about Forward&amp;Back Annotation. This section, however, lists all of the
details about what exactly happens during f/b activities:
<ul>
<li>When adding a new part to a schematic, the part's package is added
to the board at the lower left corner of the drawing.
If the part contains power pins (pins with Direction "Pwr") the related
pads will be automatically connected to their power signals.
<li>When deleting a part from a schematic drawing, the part's package is
deleted from the board. Any wires that were connected to that package
are left unchanged. This may require additional vias to be set in
order to keep signals connected. These vias will <b>not</b> be set automatically!
The ratsnest will be re-calculated for those signals that were connected
to the removed package.
<li>When deleting a part from a board drawing, all of the gates contained
in that part will be deleted from the schematic. Note that this may
affect more than one sheet, if the gates were placed on different
sheets!
<li>After an operation that removes a pad from a signal that has a supply
layer, the Thermal/Annulus display may be incorrect. In such a case
a window refresh will show the correct Thermal/Annulus symbols.
The same applies to Undo/Redo operations that involve pads connected
to supply layers.
<li>A PinSwap or GateSwap operation in the schematic will make all the
necessary changes to the wires of the board. However, after this
operation the wires may overlap or violate minimum distance rules.
Therefore the user should take a look at these wires and modify them
with Move, Split, Change Layer etc.
<li>To make absolutely sure that a board and schematic belong to each
other (and are therefore connected via Forward&amp;Back Annotation)
the two files must have the same file name (with extensions .brd and .sch)
and must be located in the same directory!
<li>The Replace command checks whether all pads in the old package which
have been assigned to pins will also be present in the new package,
regardless whether they are connected to a signal or not.
<li>When the pins of two parts in the schematic are directly overlapping
(and thus connected without a visible net wire), a net wire will be
generated when these parts are moved away from each other.
This is done to avoid unnecessary ripup of signal wires in the board.
</ul>
<a name=342>
<h1>Consistency Check</h1>
In order to use Forward&amp;Back Annotation a board and schematic
must be consistent, which means they must contain an equivalent set of
parts/elements and nets/signals.
<p>
Normally a board and schematic will always be consistent as long as they
have never been edited separately (in which case the message
<i>"No Forward&amp;Back Annotation will be performed!"</i>
will have warned you).
<p>
When loading a pair of board and schematic files the program will check
some consistency markers in the data files to see if these two files are
still consistent. If these markers indicate an inconsistency, you will be
offered to run an <a href=#48>Electrical Rule Check</a> (ERC),
which will do a detailed cross-check on both files.
<p>
If this check turns out positive, the two files are marked as consistent
and Forward&amp;Back Annotation will be activated.
<p>
If the two files are found to be inconsistent the ERC protocol file will
be brought up in a dialog and Forward&amp;Back Annotation will
<b>not</b> be activated.
<p>
<b>Please do not be alarmed if you get a lot
of inconsistency messages. In most cases fixing one error (like renaming
a part or a net) will considerably reduce the number of error messages you get in the next
ERC run.</b>
<h2>Making a Board and Schematic consistent</h2>
To make an inconsistent pair of board and schematic files consistent, you
have to manually fix any inconsistency listed in the ERC protocol.
This can be done by applying editor commands like
<a href=#68>NAME</a>,
<a href=#103>VALUE</a>,
<a href=#76>PINSWAP</a>,
<a href=#86>REPLACE</a> etc.
After fixing the inconsistencies you must use the
<a href=#48>ERC</a> command again to check the files and
eventually activate Forward&amp;Back Annotation.
<a name=343>
<h1>Limitations</h1>
The following actions are not allowed in a board when Back Annotation
is active (i.e. the schematic is loaded, too):
<ul>
<li>adding or copying a part that contains Pads or Smds
<li>deleting an airwire
<li>defining connections with the Signal command
<li>pasting from a board into a board, if the pasted objects contain
parts with Pads or Smds, or Signals with connections
</ul>
If you try to do one of the above things, you will receive a message
telling you that this operation cannot be backannotated. In such a
case please do the necessary operations in the schematic (they will
then be forward annotated to the board). If you absolutely have to
do it in the board, you can close the schematic window and then do
anything you like inside the board. In that case, however, board and
schematic will not be consistent any more!
<a name=344>
<h1>Technical Support</h1>
As a registered EAGLE user you get free technical support from CadSoft.
There are several ways to contact us or obtain the latest part libraries,
drivers or program versions:
<p>
CadSoft Computer<br>
19620 Pines Blvd. Suite 217<br>
Pembroke Pines, FL 33029<br>
USA
<p>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td>Phone </td><td width=20><td>954-237-0932</td></tr>
<tr><td>Fax </td><td width=20><td>954-237-0968</td></tr>
<tr><td>Email </td><td width=20><td>support@cadsoftusa.com</td></tr>
<tr><td>URL </td><td width=20><td>www.cadsoftusa.com</td></tr>
</table>
<a name=345>
<h1>License</h1>
To legally use EAGLE you need a registered user license.
Please check whether the dialog "Help/About EAGLE" contains your name and address
under "Registered to:".
If you have any doubts about the validity or authenticity of your license,
please contact our
<a href=#344>Technical Support</a> staff
for verification.
<table><tr><td valign="top"><img src="platforms-mac.png"></td><td valign="middle">
Under <b>Mac OS X</b> you can find this information under "EAGLE/About EAGLE".
</td></tr></table>
<p>
There are different types of licenses, varying in the number of users
who may use the program and in the areas of application the program
may be used in:
<h2>Single-User License</h2>
Only <b>one</b> user may use the program at any given time.
However, that user may install the program on any of his computers, as long
as he makes sure that the program will only be used on one of these
computers at a time.
<p>
A typical application of this kind would be a user who has a PC at home
and also a notebook or laptop computer which he uses "on the road". As
he would only use one of these computers at a time it is ok to have EAGLE
installed on both of them.
<h2>Multi-user License</h2>
A multi-user license may be used by several users (up to the maximum number
listed on the license) simultaneously. The program may be installed on any
number of different computers at the location of the license holder.
<h2>Commercial License</h2>
The program may be used for any purpose, be it commercial or private.
<h2>Educational License</h2>
The program may only be used in an educational environment like a school,
university or training workshop, in order to teach how to use ECAD
software.
<h2>Student License</h2>
The program may only be used for private ("non-profit") purposes.
Student versions are sold at a very low price, to allow people who
could otherwise never afford buying EAGLE the use of the program
for their private hobby or education. It is a violation of the license
terms if you "earn money" by using a Student Licence of EAGLE.
<a name=346>
<h1>EAGLE License</h1>
Before you can work with EAGLE it is necessary to register the program with
your personalized license data.
<p>
In the dialog "EAGLE License" enter the name of your EAGLE license file, as well
as the corresponding Installation Code you have received together with your
license file (this code consists of 10 lowercase characters).
<p>
After pressing enter or clicking on the
<b>OK</b>
button, EAGLE will be installed with your personalized license data.
<p>
If you have problems installing EAGLE or are in doubt about the
validity of your license please contact our
<a href=#344>Technical Support</a> staff for
assistance.
<h2>Installing additional modules</h2>
If you decided to update your license with the schematic/autorouter module
you get a new license file with a new Installation Code.
To make the new modules available you have to register your EAGLE again.
Start the EAGLE program and choose in the <a href=#12>Control Panel</a>
in the Help menu the item <i>EAGLE License</i>.
<a name=347>
<h1>EAGLE Editions</h1>
EAGLE is available in three different editions to fit various
user requirements.
<h2>Professional</h2>
The <i>Professional</i> edition provides full functionality:
<ul>
<li>board area up to 1600x1600mm (64x64inch)
<li>up to 16 routing layers
<li>up to 999 sheets per schematic
</ul>
<h2>Standard</h2>
The <i>Standard</i> edition has the following limitations:
<ul>
<li>board area limited to 160x100mm (6.3x4inch), which corresponds to a full Eurocard
<li>only four routing layers (Top, Route2, Route15 and Bottom)
<li>a schematic can consist of up to 99 separate sheets
</ul>
<h2>Light</h2>
The <i>Light</i> edition has the following limitations:
<ul>
<li>board area limited to 100x80mm (4x3.2inch), which corresponds to half of a Eurocard
<li>only two routing layers (Top and Bottom)
<li>a schematic can consist of only one single sheet
</ul>
<p>
If you receive an error message like
<p>
<i>The Light edition of EAGLE can't perform the requested action!</i>
<p>
this means that you are attempting to do something that would violate
the limitations that apply to the EAGLE edition in use, like for example
placing an element outside of the allowed area.
<p>
Both the <i>Standard</i> and <i>Light</i> edition of EAGLE can be
used to view files created with the <i>Professional</i> edition,
even if these drawings exceed the editing capabilities of the edition
currently in use.
<p>
To check which edition your license has enabled, select
<i>Help/About EAGLE</i> from the Control Panel's menu.
</body>
</html>
View Git Blame Copy Permalink