From 6660c3f7d022faca95682c71b681cd6f760d40ac Mon Sep 17 00:00:00 2001 From: Matthias Koefferlein Date: Thu, 3 Aug 2017 21:43:53 +0200 Subject: [PATCH] Updated documentation. --- src/lay/doc/programming/introduction.xml | 69 +++++++++++++----------- 1 file changed, 38 insertions(+), 31 deletions(-) diff --git a/src/lay/doc/programming/introduction.xml b/src/lay/doc/programming/introduction.xml index a807c8318..331cada45 100644 --- a/src/lay/doc/programming/introduction.xml +++ b/src/lay/doc/programming/introduction.xml @@ -16,34 +16,36 @@

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

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

- 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 . From version 0.22, generic macros are supported which offer some advantages - over plain text files. + Basically there are scripts and macros:

-

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

+

Before you start, please make yourself familiar with the macro development integrated environment (). @@ -169,8 +171,15 @@ end

- 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: +

+ + 
  lv = LayoutView.current || raise "Shape Statistics: No view selected"
+ +

+ 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

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

- -

- 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: 

  lv.each_object_selected do |sel|
@@ -215,7 +221,7 @@ end
"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 ().

@@ -223,9 +229,9 @@ end

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 (), 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 (), 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 (), a Box (), a Text () or a Path object (). For our sample however we don't need access to the actual object. @@ -246,7 +252,8 @@ end 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.