luke
/
klayout
mirror of https://github.com/KLayout/klayout.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updated documentation.

This commit is contained in:
Matthias Koefferlein 2017-08-03 21:43:53 +02:00
parent 4f48cd5dab
commit 6660c3f7d0
1 changed files with 38 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
src/lay/doc/programming/introduction.xml
View File

@ -16,34 +16,36 @@
</p>
<p>
To use RBA scripts, KLayout must be compiled with the Ruby interpreter.
On Linux, this is automatically the case when the build script is run with a Ruby interpreter in
the path and when the Ruby development packages are installed (on Debian these packages are "ruby-1.9.1" and "ruby1.9.1-dev" for example).
A Ruby version more recent than 1.9 is recommended. Ruby 2.0 and later versions are supported too.
To use RBA scripts, KLayout must be compiled with the Ruby interpreter. Check under "Help/About" whether
support is available. If there is, the "Build options" will include a "Ruby" or "Python" interpreter or both.
RBA scripts require a Ruby interpreter. To use pya scripts, Python support must be included.
</p>
<p>
To use pya scripts, KLayout must be compiled with the Python interpreter.
On Linux, this is automatically the case when the build script is run with a Python interpreter in
the path and when the Python development packages are installed.
A Python version more recent than 2.7 is recommended. Python 3.0 and later versions are supported too.
KLayout comes with the Qt library included into the Ruby or Python API. This means, KLayout scripts
can access the full Qt API if Qt binding is available. Check whether "Qt bindings for scripts" is included
in the build options on the "Help/About" page.
</p>
<p>
Basically there are a traditional, script-based style of programming and the macro-based style supported by version 0.22.
Scripts are simple text files which are prepared externally and KLayout acts as an interpreter for these scripts.
That traditional style was the only way to run scripts in version 0.21 and earlier. It is still supported and described
in <link href="/programming/traditional.xml"/>. From version 0.22, generic macros are supported which offer some advantages
over plain text files.
Basically there are scripts and macros:
</p>
<p>
Macros are special XML files which contain Ruby code plus some additional information required to
link them into the system, i.e. automatically execute them on startup or provide menu entries for them.
They can load normal ".rb" files to implement libraries of classes in the usual way. Macros are managed and developed conveniently
in the integrated macro development environment along with the supporting files. This method is the preferred way of creating application
extensions and is described in this chapter.
</p>
<ul>
<li>
<b>Scripts</b> are simple text files which are prepared externally and KLayout acts as an interpreter for these scripts.
A special case of scripts is included code, while is loaded into other scripts or macros using "require" on Ruby
or "import" on Python. Scripts have been the only way to code Ruby functionality in version 0.21 and earlier.
That way is still supported, but deprecated (See <link href="/programming/traditional.xml"/>).
</li>
<li>
<b>Macros</b> are special XML files which contain Ruby code plus some additional information required to
link them into the system, i.e. automatically execute them on startup or provide menu entries for them.
They can load normal ".rb" or ".py" files to implement libraries of classes in the usual way. Macros are managed and developed conveniently
in the integrated macro development environment along with the supporting files. This method is the preferred way of creating application
extensions and is described in this chapter.
</li>
</ul>
<p>
Before you start, please make yourself familiar with the macro development integrated environment (<link href="/about/macro_editor.xml"/>).
@ -169,8 +171,15 @@ end</pre>
</p>
<p>
The actual layouts loaded are separate entities. Technically, there is a many-to-many relationship between layout views
and layout objects. A layout view may display multiple layouts are one layout may be displayed in multiple layout views.
Actually the preparation step can be simplified without needing the Application and MainWindow object. For demonstration
purposes it was included however. Here is the short version:
</p>
<pre> lv = LayoutView.current || raise "Shape Statistics: No view selected"</pre>
<p>
The actual layouts loaded are entities separated from the views. Technically, there is a many-to-many relationship between layout views
and layout objects. A layout view may display multiple layouts and one layout may be displayed in multiple layout views.
In addition, a layout view can address different cells from a layout. A layout view has a current cell and a path
that leads to that cell. The path consists of a specific and unspecific part. The unspecific part of the path tells
where the cell we show as the current cell is located in the cell tree. The unspecific part is a tribute to the fact that
@ -189,10 +198,7 @@ end</pre>
<p>
For our sample we don't need the CellView objects, because we get all information directly from the view. But the
concept of that object is important to understand the API documentation.
</p>
<p>
In our sample, we ask the layout view for all selected objects and collect the object counts:
Here we ask the layout view for all selected objects and collect the object counts:
</p>
<pre> lv.each_object_selected do |sel|
@ -215,7 +221,7 @@ end</pre>
"each_object_selected" is a method of the LayoutView object. More precisely it's an iterator which calls the
given block for each selected object. Since the layout view can show multiple layouts, the selected objects may
originate from different layouts. In addition, the object may be selected in a child cell of the current cell.
Hence, the selection is described by a cell view index, an instantiation path (a sequence of instances leading to
Hence, the selection is described by a cell view index (indicating which layout it resided in), an instantiation path (a sequence of instances leading to
the cell containing the selected object from the current cell) and the actual object selected.
That information is combined into an ObjectInstPath object (<class_doc href="ObjectInstPath"/>).
</p>
@ -223,9 +229,9 @@ end</pre>
<p>
In our case we are not interested in the cell view that shape lives in. Neither are we in the instantiation path.
Hence all we need is the shape and we can obtain it with the "shape" method.
This method delivers a Shape object (<class_doc href="Shape"/>), which is some kind of pointer to the
actual shape. The actual shape is either a polygon, a box, a text or a path. The Shape object has a multiple
identity and we can ask it what shape type is represents. For that, the Shape object offers methods like "is_box?" etc.
This method delivers a Shape object (<class_doc href="Shape"/>), which is some kind of pointer (a "proxy") to the
actual shape. The actual shape is either a polygon, a box, a text or a path. The Shape object has multiple
identities and we can ask it what shape type is represents. For that, the Shape object offers methods like "is_box?" etc.
If we know the type we can ask it for the actual object and fetch a Polygon (<class_doc href="Polygon"/>), a
Box (<class_doc href="Box"/>), a Text (<class_doc href="Text"/>) or a Path object (<class_doc href="Path"/>).
For our sample however we don't need access to the actual object.
@ -246,7 +252,8 @@ end</pre>
MessageBox (<class_doc href="MessageBox"/>) is a class that provides modal message dialogs through
several class methods. "info" shows an information box and with the given title and message. The third
parameter indicates which buttons will be shown. In that case, one "Ok" button is sufficient because
we don't want to take specific actions when the message box is closed.
we don't want to take specific actions when the message box is closed. MessageBox is not the Qt class,
which is also available (QMessageBox), but less portable in case a user does not have Qt binding enabled.
</p>
<p>